i18n Approach

[emjunior258]

Overview

The new I18N approach relies entirely on the server-side to allow internationalisation. The Client-side has no translation capability. In cases a client-side script needs to use an internationalised string, the string must be explicitly passed from the server-side to the client-side so that it can be available. In other words: translation is only available on the server-side.

Specification

International string

Is a string that must change according to the user's language.

Language dictionary

Is a collection of international strings. Language dictionaries allow applications to keep international strings in separated files, grouping them by context. For example: An app could have two language dictionaries: labels and messages and another app could have four language dictionaries: error-messages, button-labels, success-messages, question-messages. It would depend in how the developer wants to group the international strings.

Language dictionary file

Is a Java properties file containing internal strings and their respective translations.

Language

Is a set of language dictionaries.

Default Language

Is the language in which the application was written.

Language dictionary files location

+ src
|       + main
|        |       + webapp
|        |        |     + i18n
|        |        |      |      +lang1
|        |        |      |       |     - dictionary1.properties
|        |        |      |       |     - dictionary2.properties
|        |        |      |       |     - dictionaryn.properties
|        |        |      |      +lang2
|        |        |      |       |     - dictionary1.properties
|        |        |      |       |     - dictionary2.properties
|        |        |      |       |     - dictionaryn.properties 

Examples

configuration fragment

<i18n>
        <enable-concatenation>true</enable-concatenation> <!--false by default-->
        <policy>TRANSLATE_ON_DEMAND</policy>
         <!--Optional-->
        <use-cache>com.package.whatever.CacheImpl</use-cache>

        <languages>
            <language default="true">pt</language>
            <language>en</language>
        </languages>

        <dictionaries>
            <dictionary>labels</dictionary>
            <dictionary>messages</dictionary>
        </dictionaries>

</i18n>

Classpath lookup

Tells if Hi-Framework should scan each jar looking for Language dictionary files.

Policy

Defines the moment to apply translations on views HTML files. There two possible values: TRANSLATE_ON_DEMAND and TRANSLATE_ON_DEPLOYMENT.

Cache

Defines a cache to be used to store translated views HTML.

Exporting a string to the client-side

On template load

   @Inject
   private I18nContext i18n

   public void example(@Observes TemplateLoadEvent event){

          i18n.export("string to export"); //export an international string
          i18n.export("string to export","variable");  //export an international string with an alias 
          i18n.exportDictionary("name");  //export all strings in a dictionary

  }

From a controller action

   @Inject
   private I18nContext i18n

   public void action(Map arguments){

          i18n.export("string to export"); //export an international string
          i18n.export("string to export","variable");  //export an international string with an alias 
          i18n.exportDictionary("name");  //export all strings in a dictionary

  }

Accessing international strings from client-side

   //Approach A
   var string = i18n.get("alias or string"); //Hello mr {{name}}.
   var values = {name:"Mario Junior"};
   var compiledString = i18n.get("alias or string",values);

   //Approach B
   var international = translate("alias or string").with({name:"Mario Junior"});

Language dictionary files concatenation

When classpath-lookup is enabled, Hi-Framework might find multiple language dictionary files with the same name under the same path. It will automatically concatenate such files and deal with them as if they were a single file.

Implications

Views HTML caching

Hi-Frameworks currently caches views on the client-side. The new i18n approach would change the way the the views caching works on client-side. Changing the user language will automatically cleanup the views cache on the client-side.