1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
4<html xmlns="http://www.w3.org/1999/xhtml">
5  <head>
6    <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
7    <title>Localization</title>
8    <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
9    <link rel="stylesheet" type="text/css" href="css/prettify.css" />
10  </head>
11  <body onload="prettyPrint()">
12
13    <script type="text/javascript">prefix='';</script>
14
15    <script type="text/javascript" src="js/prettify.js"></script>
16    <script src="templates/header.js" type="text/javascript"></script>
17    <div id="left">
18      <noscript>Please turn on Javascript to view this menu</noscript>
19      <script src="templates/left.js" type="text/javascript"></script>
20    </div>
21
22    <div id="content">
23
24
25    <h1>Localization support</h1>
26
27    <p>A <a
28    href="http://markmail.org/thread/drcabfc6z42sijdo">discussion</a>
29    on the slf4j-dev mailing list spawned an open-source project
30    called <a href="http://cal10n.qos.ch"><b>CAL10N or Compiler
31    Assisted Localization</b></a>. As its name indicates, CAL10N
32    focuses on the issue of localization/internationalization in Java
33    applications.
34    </p>
35
36    <p>The <code>org.slf4j.cal10n</code> package which ships with
37    <em>slf4j-ext-${project.version}.jar</em> adds an extremely thin
38    layer on top of CALI0N to offer localized logging.</p>
39
40
41    <p>Once you have a handle on an <a
42    href="http://cal10n.qos.ch/apidocs/ch/qos/cal10n/IMessageConveyor.html">IMessageConveyor</a>
43    instance, you can create a <a
44    href="xref/org/slf4j/cal10n/LocLoggerFactory.html">LocLoggerFactory</a>,
45    which in turn can create <a
46    href="xref/org/slf4j/cal10n/LocLogger.html">LocLogger</a>
47    instances capable of doing localized logging.
48    </p>
49
50
51    <p>Let us assume that you have defined localized message in your
52    application. In accordance with the CAL10N's philosophy, you have
53    the declared the keys for those messages in the enum type
54    <code>Production</code>.</p>
55
56
57   <pre class="prettyprint source">import ch.qos.cal10n.LocaleData;
58import ch.qos.cal10n.Locale;
59import ch.qos.cal10n.BaseName;
60
61@BaseName("production")
62@LocaleData( { @Locale("en_UK"), @Locale("ja_JP") })
63public enum Production  {
64  APPLICATION_STARTED,
65  APPLICATION_STOPPED,
66  ...
67  DB_CONNECTION,
68  DB_CONNECTION_FAILURE;
69}</pre>
70
71    <p>It is assumed that you have created appropriate bundle file for
72    the various locales "en_UK" and "ja_JP" as appropriate. Here is a
73    sample bundle for the "en_UK" locale.
74    </p>
75
76
77    <pre class="source">APPLICATION_STARTED=Application <b>{0}</b> has started.
78APPLICATION_STOPPED=Application <b>{0}</b> has stopped.
79... </pre>
80
81    <p>Then, you
82    can instantiate a <code>IMessageConveyor</code>, inject it into a
83    <code>LogLoggerFactory</code>, retrieve multiple
84    <code>LogLogger</code> instances by name and log away, as the next
85    sample code illustrates.
86    </p>
87
88
89    <pre class="prettyprint source">import java.util.Locale;
90
91import org.slf4j.cal10n.LocLogger;
92import org.slf4j.cal10n.LocLoggerFactory;
93
94import ch.qos.cal10n.IMessageConveyor;
95import ch.qos.cal10n.MessageConveyor;
96
97public class MyApplication {
98
99  // create a message conveyor for a given locale
100  IMessageConveyor  messageConveyor = new MessageConveyor(Locale.UK);
101
102  // create the LogLoggerFactory
103  LocLoggerFactory llFactory_uk = new LocLoggerFactory(messageConveyor);
104
105  // create a locLogger
106  LocLogger locLogger = llFactory_uk.getLocLogger(this.getClass());
107
108
109  public void applicationStart() {
110    locLogger.info(Production.APPLICATION_STARTED, "fooApp");
111    // ..
112  }
113
114  public void applicationStop() {
115    locLogger.info(Production.APPLICATION_STOPPED, "fooApp");
116    // ...
117  }
118}</pre>
119
120    <p>Assuming the resource bundle
121    <em>production_en_UK.properties</em> exists, and the underlying
122    logging framework is enabled for the info level, log messages will
123    be output in UK English.
124    </p>
125
126    <p>Note that a <code>LogLogger</code> is a regular SLF4J logger
127    with additional methods supporting localization. For those
128    additional methods which take an enum as first parameter,
129    <code>LogLogger</code> follows the standard Java convention for
130    parameter substitution as defined by the <a
131    href="http://java.sun.com/j2se/1.5.0/docs/api/java/text/MessageFormat.html">java.text.MessageFormat</a>
132    class. For non-localized logs, which take a String as first
133    parameter, <code>LogLogger</code> follows the {} convention, as
134    customary for all <code>org.slf4j.Logger</code> implementations.
135    </p>
136
137    <p>Here is an example illustrating the difference.</p>
138
139    <pre  class="prettyprint source">import ...;
140public class MyApplication {
141
142  IMessageConveyor  messageConveyor = new MessageConveyor(Locale.UK);
143  LocLoggerFactory llFactory_uk = new LocLoggerFactory(messageConveyor);
144  LocLogger locLogger = llFactory_uk.getLocLogger(this.getClass());
145
146  public void someMethod() {
147    // follows the MessageFormat convention
148    locLogger.info(Production.APPLICATION_STARTED, "fooApp");
149
150   // follows the {} convention
151   logLogger.info("Hello {}", name);
152   ...
153  }
154}</pre>
155    <script src="templates/footer.js" type="text/javascript"></script>
156    </div>
157  </body>
158</html>
159