Author: buildbot
Date: Wed Jun 17 12:16:30 2015
New Revision: 955119
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles/internationalization-support-i18n.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Jun 17 12:16:30 2015
@@ -1 +1 @@
-1685993
+1685996
Modified:
websites/staging/sling/trunk/content/documentation/bundles/internationalization-support-i18n.html
==============================================================================
---
websites/staging/sling/trunk/content/documentation/bundles/internationalization-support-i18n.html
(original)
+++
websites/staging/sling/trunk/content/documentation/bundles/internationalization-support-i18n.html
Wed Jun 17 12:16:30 2015
@@ -118,75 +118,71 @@
</li>
</ul>
<h3 id="jcr-repository-based-resourcebundleprovider">JCR Repository based
<code>ResourceBundleProvider</code></h3>
-<p>The sling.i18n Bundle provides the implementation of the
<code>ResourceBundleProvider</code> interface, which may also be used outside
of Sling requests for service tasks. This implementation gets the messages from
a JCR Repository stored below nodes of the mixin node type
<code>mix:language</code>. These language nodes have a
<code>jcr:language</code> property naming the language of the resources. In the
context of the JCR based <code>ResourceBundleProvider</code> this is of course
expected to be the string value of respective <code>Locale</code>.</p>
+<p>The sling.i18n Bundle provides the implementation of the
<code>ResourceBundleProvider</code> interface, which may also be used outside
of Sling requests for service tasks. This implementation gets the messages from
a JCR Repository stored below nodes of the mixin node type
<code>mix:language</code>. These language nodes have a
<code>jcr:language</code> property naming the language of the resources. In the
context of the JCR based <code>ResourceBundleProvider</code> this is of course
expected to be the string value of respective <code>Locale</code>. The format
may either be the format as described in <a
href="http://docs.oracle.com/javase/7/docs/api/java/util/Locale.html#toString%28%29";>Locale.toString</a>
or as described in <a href="https://www.ietf.org/rfc/rfc4646.txt";>RFC4646</a>
(both formats are also accepted in lower-case).</p>
+<p>The exact location of these nodes is not relevant as the
<code>ResourceBundleProvider</code> finds them by applying a JCR search.</p>
+<p>Two different types of storage formats are supported for the individual
dictionaries</p>
+<h4 id="slingmessageentry-based"><code>sling:MessageEntry</code> based</h4>
<p>The (direct) child nodes of the <code>mix:language</code> node must have
the <code>jcr:primaryType</code> set to <code>sling:MessageEntry</code> and
must contain two special properties naming the key string and the message:</p>
<ul>
-<li><code>sling:key</code> -- The <code>sling:key</code> property is a string
property being the key for which the node contains the message(s).</li>
+<li><code>sling:key</code> -- The <code>sling:key</code> property is a string
property being the key for which the node contains the message(s). This
property is optional. If it is not set the key is determined by the resource
name of the parent <code>sling:messageEntry</code>.</li>
<li><code>sling:message</code> -- The <code>sling:message</code> property
represents the resource for the key.</li>
</ul>
-<p>The exact location of these nodes is not relevant as the
<code>ResourceBundleProvider</code> finds them by applying a JCR search. It is
only required that the message nodes are located below
<code>mix:language</code> nodes. Such structures may also be scattered in the
repository to allow storing message resources next to where they are most
likely used, such as request scripts.</p>
-<h3 id="resourcebundle-with-base-names"><code>ResourceBundle</code> with base
names</h3>
-<p>Similar to standard Java <code>ResourceBundle</code> instances, Sling
<code>ResourceBundle</code> instances may be created for base names through any
of the <code>getResourceBundle(String, Locale)</code> methods. These methods
use the base name parameter as a selector for the values of the
<code>sling:basename</code> property of the <code>mix:language</code> nodes.</p>
-<p>The base name argument can take one three values:</p>
-<table>
-<thead>
-<tr>
-<th>Value</th>
-<th><code>ResourceBundle</code> selection</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td><code>null</code></td>
-<td>Selects messages of <code>mix:language</code> nodes ignoring the existence
or absence of <code>sling:basename</code> properties</td>
-</tr>
-<tr>
-<td>Empty String</td>
-<td>Selects messages of <code>mix:language</code> nodes which have
<code>sling:basename</code> properties, ignoring the actual values</td>
-</tr>
-<tr>
-<td>Any other Value</td>
-<td>Selects messages of <code>mix:language</code> nodes whose
<code>sling:basename</code> properties has any value which matches the base
name string</td>
-</tr>
-</tbody>
-</table>
-<p>The <code>sling:basename</code> property may be multi-valued, that is the
messages of a <code>mix:language</code> nodes may belong to multiple base names
and thus <code>ResourceBundle</code> instances.</p>
-<h3 id="sample-resources">Sample Resources</h3>
-<p>Consider the following repository content:</p>
+<p>It is only required that the message nodes are located below
<code>mix:language</code> nodes. Such structures may also be scattered in the
repository to allow storing message resources next to where they are most
likely used, such as request scripts.</p>
+<h5 id="sample-resources">Sample Resources</h5>
+<p>Content for dictionaries in this format might look like this:</p>
<div class="codehilite"><pre> <span class="o">/</span><span
class="n">libs</span><span class="o">/</span><span class="n">languages</span>
<span class="o">+--</span> <span class="n">English</span> <span
class="p">(</span><span class="n">nt</span><span class="p">:</span><span
class="n">folder</span><span class="p">,</span> <span class="n">mix</span><span
class="p">:</span><span class="n">language</span><span class="p">)</span>
<span class="o">|</span> <span class="o">+--</span> <span
class="n">jcr</span><span class="p">:</span><span class="n">language</span>
<span class="p">=</span> <span class="n">en</span>
- <span class="o">|</span> <span class="o">+--</span> <span
class="n">m1</span> <span class="p">(</span><span class="n">sling</span><span
class="p">:</span><span class="n">messageEntry</span><span class="p">)</span>
+ <span class="o">|</span> <span class="o">+--</span> <span
class="n">m1</span> <span class="p">(</span><span class="n">sling</span><span
class="p">:</span><span class="n">MessageEntry</span><span class="p">)</span>
<span class="o">|</span> <span class="o">|</span> <span
class="o">+--</span> <span class="n">sling</span><span class="p">:</span><span
class="n">key</span> <span class="p">=</span> "<span
class="n">msg001</span>"
- <span class="o">|</span> <span class="o">|</span> <span
class="o">+--</span> <span class="n">slign</span><span class="p">:</span><span
class="n">message</span> <span class="p">=</span> "<span
class="n">This</span> <span class="n">is</span> <span class="n">a</span> <span
class="n">message</span>"
- <span class="o">|</span> <span class="o">+--</span> <span
class="n">m2</span> <span class="p">(</span><span class="n">sling</span><span
class="p">:</span><span class="n">messageEntry</span><span class="p">)</span>
+ <span class="o">|</span> <span class="o">|</span> <span
class="o">+--</span> <span class="n">sling</span><span class="p">:</span><span
class="n">message</span> <span class="p">=</span> "<span
class="n">This</span> <span class="n">is</span> <span class="n">a</span> <span
class="n">message</span>"
+ <span class="o">|</span> <span class="o">+--</span> <span
class="n">m2</span> <span class="p">(</span><span class="n">sling</span><span
class="p">:</span><span class="n">MessageEntry</span><span class="p">)</span>
<span class="o">|</span> <span class="o">+--</span> <span
class="n">sling</span><span class="p">:</span><span class="n">key</span> <span
class="p">=</span> "<span class="n">msg002</span>"
- <span class="o">|</span> <span class="o">+--</span> <span
class="n">slign</span><span class="p">:</span><span class="n">message</span>
<span class="p">=</span> "<span class="n">Another</span> <span
class="n">message</span>"
+ <span class="o">|</span> <span class="o">+--</span> <span
class="n">sling</span><span class="p">:</span><span class="n">message</span>
<span class="p">=</span> "<span class="n">Another</span> <span
class="n">message</span>"
<span class="o">+--</span> <span class="n">Deutsch</span> <span
class="p">(</span><span class="n">nt</span><span class="p">:</span><span
class="n">folder</span><span class="p">,</span> <span class="n">mix</span><span
class="p">:</span><span class="n">language</span><span class="p">)</span>
<span class="o">+--</span> <span class="n">jcr</span><span
class="p">:</span><span class="n">language</span> <span class="p">=</span>
<span class="n">de</span>
- <span class="o">+--</span> <span class="n">m1</span> <span
class="p">(</span><span class="n">sling</span><span class="p">:</span><span
class="n">messageEntry</span><span class="p">)</span>
+ <span class="o">+--</span> <span class="n">m1</span> <span
class="p">(</span><span class="n">sling</span><span class="p">:</span><span
class="n">MessageEntry</span><span class="p">)</span>
<span class="o">|</span> <span class="o">+--</span> <span
class="n">sling</span><span class="p">:</span><span class="n">key</span> <span
class="p">=</span> "<span class="n">msg001</span>"
- <span class="o">|</span> <span class="o">+--</span> <span
class="n">slign</span><span class="p">:</span><span class="n">message</span>
<span class="p">=</span> "<span class="n">Das</span> <span
class="n">ist</span> <span class="n">ein</span> <span
class="n">Text</span>"
- <span class="o">+--</span> <span class="n">m2</span> <span
class="p">(</span><span class="n">sling</span><span class="p">:</span><span
class="n">messageEntry</span><span class="p">)</span>
+ <span class="o">|</span> <span class="o">+--</span> <span
class="n">sling</span><span class="p">:</span><span class="n">message</span>
<span class="p">=</span> "<span class="n">Das</span> <span
class="n">ist</span> <span class="n">ein</span> <span
class="n">Text</span>"
+ <span class="o">+--</span> <span class="n">m2</span> <span
class="p">(</span><span class="n">sling</span><span class="p">:</span><span
class="n">MessageEntry</span><span class="p">)</span>
<span class="o">+--</span> <span
class="n">sling</span><span class="p">:</span><span class="n">key</span> <span
class="p">=</span> "<span class="n">msg002</span>"
- <span class="o">+--</span> <span
class="n">slign</span><span class="p">:</span><span class="n">message</span>
<span class="p">=</span> "<span class="n">Ein</span> <span
class="n">anderer</span> <span class="n">Text</span>"
+ <span class="o">+--</span> <span
class="n">sling</span><span class="p">:</span><span class="n">message</span>
<span class="p">=</span> "<span class="n">Ein</span> <span
class="n">anderer</span> <span class="n">Text</span>"
<span class="o">/</span><span class="n">apps</span><span
class="o">/</span><span class="n">myApp</span>
<span class="o">+--</span> <span class="n">English</span> <span
class="p">(</span><span class="n">nt</span><span class="p">:</span><span
class="n">folder</span><span class="p">,</span> <span class="n">mix</span><span
class="p">:</span><span class="n">language</span><span class="p">)</span>
<span class="o">|</span> <span class="o">+--</span> <span
class="n">jcr</span><span class="p">:</span><span class="n">language</span>
<span class="p">=</span> <span class="n">en</span>
- <span class="o">|</span> <span class="o">+--</span> <span
class="n">mx</span> <span class="p">(</span><span class="n">sling</span><span
class="p">:</span><span class="n">messageEntry</span><span class="p">)</span>
+ <span class="o">|</span> <span class="o">+--</span> <span
class="n">mx</span> <span class="p">(</span><span class="n">sling</span><span
class="p">:</span><span class="n">MessageEntry</span><span class="p">)</span>
<span class="o">|</span> <span class="o">+--</span> <span
class="n">sling</span><span class="p">:</span><span class="n">key</span> <span
class="p">=</span> "<span class="n">msgXXX</span>"
- <span class="o">|</span> <span class="o">+--</span> <span
class="n">slign</span><span class="p">:</span><span class="n">message</span>
<span class="p">=</span> "<span class="n">An</span> <span
class="n">Application</span> <span class="n">Text</span>"
+ <span class="o">|</span> <span class="o">+--</span> <span
class="n">sling</span><span class="p">:</span><span class="n">message</span>
<span class="p">=</span> "<span class="n">An</span> <span
class="n">Application</span> <span class="n">Text</span>"
<span class="o">+--</span> <span class="n">Deutsch</span> <span
class="p">(</span><span class="n">nt</span><span class="p">:</span><span
class="n">folder</span><span class="p">,</span> <span class="n">mix</span><span
class="p">:</span><span class="n">language</span><span class="p">)</span>
<span class="o">+--</span> <span class="n">jcr</span><span
class="p">:</span><span class="n">language</span> <span class="p">=</span>
<span class="n">de</span>
- <span class="o">+--</span> <span class="n">mx</span> <span
class="p">(</span><span class="n">sling</span><span class="p">:</span><span
class="n">messageEntry</span><span class="p">)</span>
+ <span class="o">+--</span> <span class="n">mx</span> <span
class="p">(</span><span class="n">sling</span><span class="p">:</span><span
class="n">MessageEntry</span><span class="p">)</span>
<span class="o">+--</span> <span
class="n">sling</span><span class="p">:</span><span class="n">key</span> <span
class="p">=</span> "<span class="n">msgXXX</span>"
- <span class="o">+--</span> <span
class="n">slign</span><span class="p">:</span><span class="n">message</span>
<span class="p">=</span> "<span class="n">Ein</span> <span
class="n">Anwendungstext</span>"
+ <span class="o">+--</span> <span
class="n">sling</span><span class="p">:</span><span class="n">message</span>
<span class="p">=</span> "<span class="n">Ein</span> <span
class="n">Anwendungstext</span>"
+</pre></div>
+
+
+<p>This content defines two languages <em>en</em> and <em>de</em> with three
messages <em>msg001</em>, <em>msg002</em> and <em>msgXXX</em> each. The names
of the respective resources have no significance (in case the
<code>sling:key</code> is set).</p>
+<h4 id="json-file-based">JSON-file based</h4>
+<p>Since Version 2.4.2 the i18n bundle supports dictionaries in JSON-format
(<a href="https://issues.apache.org/jira/browse/SLING-4543";>SLING-4543</a>).
+Since loading such dictionaries is much faster than loading the ones based on
<code>sling:MessageEntry</code>s this format should be used preferably.
+This format is assumed if the <code>mix:language</code> resource name is
ending with the extension <code>.json</code>.
+The parser will take any "key":"value" pair in the JSON file, including those
in nested objects or arrays. Normally, a dictionary will be just a single json
object = hash map though.</p>
+<h5 id="sample-resources_1">Sample Resources</h5>
+<p>Content for this format might look like this:</p>
+<div class="codehilite"><pre> <span class="o">/</span><span
class="n">libs</span><span class="o">/</span><span class="n">languages</span>
+ <span class="o">+--</span> <span class="n">english</span><span
class="p">.</span><span class="n">json</span> <span class="p">(</span><span
class="n">nt</span><span class="p">:</span><span class="n">file</span><span
class="p">,</span> <span class="n">mix</span><span class="p">:</span><span
class="n">language</span><span class="p">)</span>
+ <span class="o">|</span> <span class="o">+--</span> <span
class="n">jcr</span><span class="p">:</span><span class="n">language</span>
<span class="p">=</span> <span class="n">en</span>
+ <span class="o">|</span> <span class="o">+--</span> <span
class="n">jcr</span><span class="p">:</span><span class="n">content</span>
<span class="p">(</span><span class="n">nt</span><span class="p">:</span><span
class="n">resource</span><span class="p">)</span>
+ <span class="o">|</span> <span class="o">+</span> <span
class="n">jcr</span><span class="p">:</span><span class="n">data</span> <span
class="p">(</span><span class="n">containing</span> <span class="n">the</span>
<span class="n">actual</span> <span class="n">JSON</span> <span
class="n">file</span><span class="p">)</span>
+ <span class="o">+--</span> <span class="n">deutsch</span><span
class="p">.</span><span class="n">json</span> <span class="p">(</span><span
class="n">nt</span><span class="p">:</span><span class="n">file</span><span
class="p">,</span> <span class="n">mix</span><span class="p">:</span><span
class="n">language</span><span class="p">)</span>
+ <span class="o">+--</span> <span class="n">jcr</span><span
class="p">:</span><span class="n">language</span> <span class="p">=</span>
<span class="n">de</span>
+ <span class="o">+--</span> <span class="n">jcr</span><span
class="p">:</span><span class="n">content</span> <span class="p">(</span><span
class="n">nt</span><span class="p">:</span><span class="n">resource</span><span
class="p">)</span>
+ <span class="o">+</span> <span class="n">jcr</span><span
class="p">:</span><span class="n">data</span> <span class="p">(</span><span
class="n">containing</span> <span class="n">the</span> <span
class="n">actual</span> <span class="n">JSON</span> <span
class="n">file</span><span class="p">)</span>
</pre></div>
-<p>This content defines two languages <em>en</em> and <em>de</em> with three
messages <em>msg001</em>, <em>msg002</em> and <em>msgXXX</em> each. The names
of the respective nodes have no significance at all because all information
required is extracted from the <code>jcr:language</code>,
<code>sling:key</code> and <code>sling:message</code> properties.</p>
-<h3
id="jcr-node-types-supporting-the-jcr-repository-based-resourcebundleprovider">JCR
Node Types supporting the JCR Repository based
<code>ResourceBundleProvider</code></h3>
+<h4
id="jcr-node-types-supporting-the-jcr-repository-based-resourcebundleprovider">JCR
Node Types supporting the JCR Repository based
<code>ResourceBundleProvider</code></h4>
<p>The sling.i18n bundle asserts the following node types:</p>
<div class="codehilite"><pre><span class="k">[mix:language]</span>
<span class="err">mixin</span>
@@ -204,9 +200,59 @@
</pre></div>
-<p>The <code>sling:Message</code> and <code>slign:MessageEntry</code> are
helper node types which may be used to create the nodes with the
<code>sling:key</code> and <code>sling:message</code> properties required by
the <code>ResourceBundleProvider</code>. The node types themselves are not
required but by defining the required properties, they may be of use.</p>
+<p>The <code>sling:Message</code> and <code>sling:MessageEntry</code> are
helper node types. The latter must be used to create the nodes for the
<code>sling:MessageEntry</code> based format.</p>
+<h3 id="resourcebundle-with-base-names"><code>ResourceBundle</code> with base
names</h3>
+<p>Similar to standard Java <code>ResourceBundle</code> instances, Sling
<code>ResourceBundle</code> instances may be created for base names through any
of the <code>getResourceBundle(String, Locale)</code> methods. These methods
use the base name parameter as a selector for the values of the
<code>sling:basename</code> property of the <code>mix:language</code> nodes.</p>
+<p>The base name argument can take one three values:</p>
+<table>
+<thead>
+<tr>
+<th>Value</th>
+<th><code>ResourceBundle</code> selection</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>null</code></td>
+<td>Selects messages of <code>mix:language</code> nodes ignoring the existence
or absence of <code>sling:basename</code> properties</td>
+</tr>
+<tr>
+<td>Empty String</td>
+<td>Selects messages of <code>mix:language</code> nodes which have
<code>sling:basename</code> properties, ignoring the actual values</td>
+</tr>
+<tr>
+<td>Any other Value</td>
+<td>Selects messages of <code>mix:language</code> nodes whose
<code>sling:basename</code> properties has any value which matches the base
name string</td>
+</tr>
+</tbody>
+</table>
+<p>The <code>sling:basename</code> property may be multi-valued, that is the
messages of a <code>mix:language</code> nodes may belong to multiple base names
and thus <code>ResourceBundle</code> instances.</p>
+<h3 id="resourcebundle-hierarchies"><code>ResourceBundle</code>
hierarchies</h3>
+<p>The dictionary entries for one <code>JcrResourceBundle</code> are always
ordered like the resource resolver search paths, so usually</p>
+<ol>
+<li>dictionary entries below <code>/apps</code></li>
+<li>dictionary entries below <code>/libs</code></li>
+<li>dictionary entries anywhere else (outside the search path)</li>
+</ol>
+<p>That means that the message for the same key in <code>/apps</code>
overwrites the one in <code>/libs</code> (if both are for the same locale and
base name). Within those categories the order is non-deterministic, so if there
are two entries for the same key in <code>/apps/...</code> (for the same locale
and base name), any entry may be used.</p>
+<p>The resource bundles of the same base name with different locales also form
a hierarchy. Each key is looked up recursively first in the ResourceBundle
itself and then within its parent ResourceBundle. The parent resource bundle is
the one having the same base name and the parent locale.</p>
+<p>The locale hierarchy is ordered like this:</p>
+<ol>
+<li><code><Language> <Country> <Variant></code></li>
+<li><code><Language> <Country></code></li>
+<li><code><Language></code></li>
+<li><code><Default Locale></code>, usually <code>en</code></li>
+</ol>
+<p>So for the locale <code>de-DE-MAC</code> the fallback order would be</p>
+<ol>
+<li><code>de-DE-MAC</code></li>
+<li><code>de-DE</code></li>
+<li><code>de</code></li>
+<li><code>en</code></li>
+</ol>
+<p>The last resort (root resource bundle in all hierarchies) is always the
bundle which returns the requested key as the value.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1670025 by rombert on Mon, 30 Mar 2015 09:29:56 +0000
+ Rev. 1685996 by kwin on Wed, 17 Jun 2015 12:16:12 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
