Home » Documentation » Bundles

Internationalization Support (i18n)

Internationalization support in Sling consists of four methods in the SlingHttpServletRequest interface:

These methods have a default implementation in the org.apache.sling.core bundle and an extended and extensible implementation in the org.apache.sling.i18n bundle.

Default Implementation in the org.apache.sling.engine Bundle

The default implementation of the above mentioned four methods in the Sling Engine bundle is contained in the bundle-private class org.apache.sling.engine.impl.SlingHttpServletRequestImpl which is the primary implementation of the SlingHttpServletRequest interface:

NOTE: Unlike the default implementations of the ResourceBundle abstract class in the Java Runtime -- PropertyResourceBundle and ListResourceBundle -- the ResourceBundle returned by the default implementation of the getResourceBundle(Locale) and getResourceBundle(String, Locale) always returns a string message for any key, which is the key itself. This prevents throwing MissingResourceException.

Extensible Implementation in the org.apache.sling.i18n Bundle

The org.apache.sling.i18n Bundle implements a request level Filter providing extensible implementations of the above mentioned three methods. Extensibility is attained by defining two service interfaces:

JCR Repository based ResourceBundleProvider

The sling.i18n Bundle provides the implementation of the ResourceBundleProvider 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 mix:language. These language nodes have a jcr:language property naming the language of the resources. In the context of the JCR based ResourceBundleProvider this is of course expected to be the string value of respective Locale.

The (direct) child nodes of the mix:language node must contain two special properties naming the key string and the message:

The exact location of these nodes is not relevant as the ResourceBundleProvider finds them by applying a JCR search. It is only required that the message nodes are located below mix:language 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.

ResourceBundle with base names

Similar to standard Java ResourceBundle instances, Sling ResourceBundle instances may be created for base names through any of the getResourceBundle(String, Locale) methods. These methods use the base name parameter as a selector for the values of the sling:basename property of the mix:language nodes.

The base name argument can take one three values:

Value ResourceBundle selection
null Selects messages of mix:language nodes ignoring the existence or absence of sling:basename properties
Empty String Selects messages of mix:language nodes which have sling:basename properties, ignoring the actual values
Any other Value Selects messages of mix:language nodes whose sling:basename properties has any value which matches the base name string

The sling:basename property may be multi-valued, that is the messages of a mix:language nodes may belong to multiple base names and thus ResourceBundle instances.

Sample Resources

Consider the following repository content:

           +-- English (nt:folder, mix:language)
           |    +-- jcr:language = en
           |    +-- m1 (sling:messageEntry)
           |    |    +-- sling:key = "msg001"
           |    |    +-- slign:message = "This is a message"
           |    +-- m2 (sling:messageEntry)
           |         +-- sling:key = "msg002"
           |         +-- slign:message = "Another message"
           +-- Deutsch (nt:folder, mix:language)
                +-- jcr:language = de
                +-- m1 (sling:messageEntry)
                |    +-- sling:key = "msg001"
                |    +-- slign:message = "Das ist ein Text"
                +-- m2 (sling:messageEntry)
                     +-- sling:key = "msg002"
                     +-- slign:message = "Ein anderer Text"

           +-- English (nt:folder, mix:language)
           |    +-- jcr:language = en
           |    +-- mx (sling:messageEntry)
           |         +-- sling:key = "msgXXX"
           |         +-- slign:message = "An Application Text"
           +-- Deutsch (nt:folder, mix:language)
                +-- jcr:language = de
                +-- mx (sling:messageEntry)
                     +-- sling:key = "msgXXX"
                     +-- slign:message = "Ein Anwendungstext"

This content defines two languages en and de with three messages msg001, msg002 and msgXXX each. The names of the respective nodes have no significance at all because all information required is extracted from the jcr:language, sling:key and sling:message properties.

JCR Node Types supporting the JCR Repository based ResourceBundleProvider

The sling.i18n bundle asserts the following node types:

  - jcr:language (string)

The mix:language mixin node type allows setting the jcr:language property required by the ResourceBundleProvider implementation to identify the message Locale.

  - sling:key (string)
  - sling:message (undefined)

[sling:messageEntry] > nt:hierarchyNode, sling:message

The sling:message and slign:messageEntry are helper node types which may be used to create the nodes with the sling:key and sling:message properties required by the ResourceBundleProvider. The node types themselves are not required but by defining the required properties, they may be of use.

Rev. 1552527 by fmeschbe on Fri, 20 Dec 2013 08:18:11 +0000
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.