JQueryI18N

Homepage: https://foswiki.org/Extensions/JQueryPlugin
Author(s): Michael Daum
Version: 1.2

Summary

This plugin tries to be the simplest possible solution to add internationalization to javascript. It only does message translation reading translations from the backend. It does not cover dates, numbers, gender or pluralization.

Translations

jQuery plugins may provide translations in an i18n/ subdirectory on the backend and let JQueryPlugin take care of loading the appropriate language file for the current web page. This is done by specifying the path to the i18n/ subdirectory in the plugin definition.

Here's an example definition as specified in an lib/Foswiki/Plugins/SomePlugin/EXAMPLE.pm

sub new {
    my $class = shift;

    my $this = bless(
        $class->SUPER::new(
            name       => 'Example',
            version    => '1.0',
            author     => 'First Last',
            homepage   => 'http://...',
            i18n       => $Foswiki::cfg{SystemWebName} . "/SomePlugin/i18n",
            css        => ['example.css'],
            javascript => ['example.js'],
            dependencies => ['some other plugin'],
        ),
        $class
    );

    return $this;
}

See also the lib/Foswiki/Plugins/JQueryPlugin/EMPTY.pm template as shipped with JQueryPlugin.

The i18n attribute in the plugin definition specifies the path component starting from the pub/ root of the server. This directory may hold translations for each language:

pub/System/SomePlugin/i18n/de.js
pub/System/SomePlugin/i18n/en.js
...
pub/System/SomePlugin/i18n/uk.js

Language detection

The actual language of the user's browser is detected by Foswiki already and flagged appropriately in the HTML dom element &lt. So JQueryI18N will only have to read this attribute and pick translations from the appropriate namespace of the dictionary.

The language can be changed dynamically on the client side by changing the lang attribute of the HTML dom element and then firing a change element on it to inform the I18N component to re-translate all strings again.

$("html").attr("lang", "uk").trigger("change");

Loading translations

When Foswiki renders a page, only the translations for the current language will be loaded automatically. This is done by adding a special <script> element to the page. For our example plugin this would then be

<script type="application/l10n" data-i18n-language="en" data-i18n-namespace="SOMEPLUGIN" data-src="pub/System/SomePlugin/i18n/en.js"></script>

This file will then be loaded by the I18N component and will translate all elements on the page flagged to be translatable.

Note that not all translations have to be specified in one single file. Instead translations are added incrementally to the dictionary. New %<script type="application/l10n" ...> elements might even be loaded dynamically (like when using AngularSkin).

Format of translation files

Translation files have a very simple format holding a single json object of this form:

{
   "message-key": "translation",
   "Hello World": "Hallo Welt",
   "Hello %name%": "Hallo %name%",
...
}

Note that when a message-key was not found in the dictionary will the translation default to the message key itself.

Inline translations

Translations could also be inlined to the current page this way:

<script type="application/l10n" data-i18n-language="en">
{
   "message-key": "translation",
...
   "message-key": "translation"
}
</script>

Actual key-value pairs in this dictionary follow the same format as if it was loaded asynchronously from the backend.

Translating a string

There are two ways of translating strings:

• via the javascript API
• using declarative HTML

This is how to translate a string using the javascript API: $.i18n(string, params). For example:

var translation = $.i18n("Hello %name%, time to get up. It's already %time%", {
   name: "Fred",
   time: (new Date()).toLocaleString()
});

This will take the message key and parameters and replace all occurrences of %name% and %time% with values as specified in the params object.

DOM elements holding strings could also be translated automatically without explicitly calling the javascript API.

<span class="i18n" data-i18n-message="Hello %wikiname%" data-i18n-wikiname="%WIKINAME%">foo bar</span>

As soon as a dictionary has been loaded will all elements of class="i18n" be processed. The message key specified in the =data-i18n-message=" attribute will be processed and replaces the inner html if the element: "foo bar" will be replaced with "Hello WikiGuest".

Whenever the current language changes or a the dictionary has been updated incrementally will all i18n dom elements be re-translated again.