Nov 4, 2021 2:41:39 PM Thomas Dumont avatar

Internationalization (i18n)

Presentation

It is possible to adapt the content of a Lutèce application according to the context of the user (language, country ...). For this, Lutèce relies on the recommendations and tools offered by the Java platform. The texts handled by the application are replaced by keys listed in "properties" files where they are associated with a label. The same keys are included in different files with a suffix specifying the context. For example :

  • myplugin_messages.properties - default language
  • myplugin_messages_fr.properties - french
  • myplugin_messages_fr_FR.properties - french (France)
  • myplugin_messages_en_CA.properties - French (Canada)
  • myplugin_messages_en_US.properties - English (United States)
  • ...

When creating the content, the file is selected by the ResourceBundle class according to the locale defined for the user (variable representing a context, particularly based on a language and a country).

File and key Rules

In order for Lutece to determine in which file to search for a key, the name and location of the resource files are subject to the following rules according to the type of component :

Type of component File Location Construction of the key
Lutece Core Subsystem src/java/fr/paris/lutece/portal/resources/<subsystem>_messages.properties portal.<subsysteme>.<template>.<label>
Plugin src/java/fr/paris/lutece/<plugin>/resources/<plugin>_messages.properties <plugin>.<template>.<label>
Module of a Plugin src/java/fr/paris/lutece/<plugin>/modules/<module>/resources/<module>_messages.properties module.<plugin>.<module>.<template>.<label>

wherein :

  • <subsystem> is a name given to the Core subsystem
  • <plugin> is a name given to the plugin
  • <module> is a name given to the module
  • <template> is a name given to the template in which the label will be used (ex: create_document)
  • <label> is a name given to the label (ex: labelDocumentTitle)

Internationalization in templates

You must indicate the location of the labels to be internationalized in the templates by inserting #i18n followed by the i18n key corresponding to the label in braces :

<h2>#i18n {document.create_document.title} ${document_type}</h2>
<div class="form-group">
<p>
    <label for="document_title">#i18n {document.create_document.labelDocumentTitle} * : </label>
    <input type="text" name="document_title" size="80" maxlength="255"/> 
    <span class="help-block" > #i18n {document.create_document.helpDocumentTitle} </span>
</p>
...

Labels i18n with parameters

New LUTECE v5.0

It is possible to pass parameters to an i18n label using the pattern of the Java MessageFormat class in the myplugin_messages.properties resource file:

mykey.message = My message using 2 arguments: {0} and {1}

Warning ! See in the Java documentation the particularities of MessageFormat, especially regarding the escapement (the single quotes must for example be doubled to be correctly taken into account: mykey.message=Let''s display of {0})

The #18n is replaced by ${i18n( "key", arg1, ... )} as follows :

${i18n( "myplugin.mykey.message", argument1, argument2 )}

Internationalization in Java code

In Java code, use the I18nService service for locate a key based on the current locale. The values ​​of the keys must be declared in constants as below :

private static final PROPERTY_MESSAGE_MYMESSAGE = "myplugin.myMessage";

...
String strLocalizedMessage = I18nService.getLocalizedString( PROPERTY_MESSAGE_MYMESSAGE, locale );
...

Value overload i18n

New LUTECE v5.0

The default values ​​of the i18n keys can be overloaded in files placed under /WEB-INF/conf/override/ (by default) and respecting the same tree. So to overload keys of myplugin_messages.properties, you will have to put them in /WEB-INF/conf/override/fr/paris/lutece/myplugin/resources/myplugin_messages.properties.

It is not necessary to redefine all keys in these files. A mechanism allows to recover the keys of the original file when they have not been redefined.