Simple Use Case: YAHOO.plugin.Translator

You can use this package to separate the language sentences from your current javascript component, usually the solution is release different components for different languages, but this is painful for the maintaining process because you will have different version of the component for each language, also is a problem to the community to collaborate with you in the creation of different language package for a component because the collaborators need to change your code to change the sentences.

Includes:

<script type="text/javascript" src='/PATH/TO/yui/build/utilities/utilities.js'></script>
<script type="text/javascript" src='/PATH/TO/yui-cms/build/ext/json.js'></script>
<script type="text/javascript" src='/PATH/TO/yui-cms/build/translator/translator.js'></script>

Script:

// this line is not neccesary it you will not use module language onDemand. 
YAHOO.plugin.Translator.init ({lang:'eng', uri:'/PATH/TO/translator-gateway.php', charset:'UTF-8'});
YAHOO.plugin.Translator.set ('COMMON', {
  _YES: 'Si',
  _NO: 'No'
});
alert ( '_YES'.translate('COMMON') );  // equal to: YAHOO.plugin.Translator.get ('COMMON', '_YES');
alert ( '_NO'.translate() ); // equal to: YAHOO.plugin.Translator.find ('_YES');

The Translator Manager will try to translate the string (propotype STRING) if you specify the module, and the translator plugin will try to find or load the current language sentence. If you don't specify the module, the translator plugin will try to find the sentence thru the list of available modules without load nothing thru the network.

Singleton: YAHOO.plugin.Translator

Init the translator plugin:
YAHOO.plugin.Translator.init(obj userConfig);

Arguments:
(1) userConfig Object: JS object defining the configuration for the translator plugin. See Configuration section for full list.

---

Load a remote language module:
YAHOO.plugin.Translator.load(str id, obj modConfig);

Arguments:
(1) id: the module id (don't matter if the module is already loaded, the translator will fetch it again).
(2) Configuration Object: JS object defining configuration properties for the module. See Configuration section for full list.

---

Set a language module:
YAHOO.plugin.Translator.set(str id, obj values);

Arguments:
(1) id: the module id (don't matter if the module is already loaded, the translator will override the values but will keep the configuration).
(2) values Object: JS object defining all the language sentences for this module.

---

Translate a certain language sentence:
YAHOO.plugin.Translator.get(str id, str c, obj config);

Arguments:
(1) id: the module id.
(2) c: the language sentence to be translated.
(3) config Object: JS object defining the configuration for remote loading and important moments during the loading process.

---

Translate a certain language sentence without use the module name (logical search thru all the modules):
YAHOO.plugin.Translator.find(str c);

Arguments:
(1) c: the language sentence to be translated.

---

Adding a new module language:
YAHOO.plugin.Translator.add(str id, obj values, obj config);

Arguments:
(1) id: the module id.
(2) values Object: JS object defining all the language sentences for this module.
(3) config Object: JS object defining the configuration for remote loading and important moments during the loading process.

---

Reloading all the modules:
YAHOO.plugin.Translator.reload(); // loading all the modules information using AJAX

---

Clearing a module language:
YAHOO.plugin.Translator.reset(str id, obj modConfig);

Arguments:
(1) id: the module id.
(2) config Object: JS object defining the configuration for remote loading and important moments during the loading process.

---

Checking the state of a certain module:
YAHOO.plugin.Translator.isReady(str id);

Arguments:
(1) id: the module id.

Solutions:

Loading language module from a custom path:

YAHOO.plugin.Translator.load( 'MY-CUSTOM-MODULE', {
    uri: '/PATH/TO/my-custom-module.json',
    onReady: function () {
       alert ( ''_MY_TITLE_1''.translate('MY-CUSTOM-MODULE') );
    },
    onError: function () {
        alert ( 'Error loading the Custom Module using the Translator Plugin...' );
    }
});

---

Warranting the correct encoding:

YAHOO.plugin.Translator.init ({lang:'esp', charset:'iso-8859-1'});

In this case, we define a different charset for "spanish" language, and the translator gateway (/translator.php by default) will transform the JSON string from ISO-8859-1 to UTF-8 before sending the response to the client, warranting the correct encoding's process. This technique is used because the default header and charset for AJAX request / response is UTF-8, even when the current page has a different charset (meta: content-type).

---

How work the translator gateway:

The translator gate (/translator.php by default) just the the params of the request, and response with the correct module language using a simple technique:

Request:
/translator.php?lang=esp&module=feed&charset=iso-8859-1

Response:

{
    "CMO_RSS": 'RSS',
    "CMO_RSS_BLOGLINES": 'Adicionar a Bloglines',
    "CMO_RSS_YAHOO": 'Adicionar a Mi Yahoo!',
    "CMO_RSS_GOOGLE": 'Adicionar a Google Reader',
    "CMO_RSS_NETVIBES": 'Adicionar a Netvibes',
    "CMO_RSS_MSN": 'Adicionar a Mi MSN',
    "CMO_RSS_NEWSGATOR": 'Adicionar a Newsgator',
    "CMO_RSS_LIVE": 'Otra Applicación...',
    "MCMS_CLOSE": 'Cerrar'
}

In the translator gateway will return the file store in this path:
/yui-cms/build/feed/lang/esp.json

and this json file will be transformed from ISO-8859-1 to UTF-8 before sending the response to the browser.

---

Common module structure:
/yui-cms/build/feed/feed-min.js
/yui-cms/build/feed/feed.js
/yui-cms/build/feed/assets/feed.css
/yui-cms/build/feed/lang/eng.json
/yui-cms/build/feed/lang/esp.json
/yui-cms/build/feed/lang/fra.json

The translator gateway concate the params to load certain package:
/ yui-cms / build / {$_GET['module']} / lang / {$_GET['lang']} . json

You can build your own translator gateway for your library using a simple PHP script, and defining the new path in the initialization proces:
YAHOO.plugin.Translator.init ({lang:'esp', charset:'iso-8859-1', uri:'/PATH/TO/YOUR/CUSTOM/translator.php' });

---

Dynamic language switching:

The translator plugin allow to switch all the module to another language using this:
YAHOO.plugin.Translator.init ({lang:'esp', charset:'iso-8859-1'});
YAHOO.plugin.Translator.reload ();

Using the "reload" method after the initialization (the initialization method can be used in time your need it), all the languages will be reloaded from the server using AJAX.

Key Interesting Moments in Translator

Events	Fires	Arguments
onNull	...when certain language sentence don't exists in a certain module	[0] module: module name, [1] c: language constant
onError	...when error accour during the loading process
onReady	...when a new module is ready (loaded)

Key Translator Configuration Options

Option (type)	Default	Description
lang (s)	eng	GUI to identity the current language
uri (s)	/translator.php	The local gateway to load language module onDemand
chatset (s)	UTF-8	Encoding used by the gateway to transform certain json string to UTF-8

Translator JSON Structure (example)

{
        "CMO_BOOKMARK": 'Bookmark',
        "CMO_BOOKMARK_MENEAME": 'Add to Meneame',
        "CMO_BOOKMARK_DIGG": 'Add to Digg',
        "CMO_BOOKMARK_DELICIOUS": 'Add to Del.icio.us',
        "CMO_BOOKMARK_TECHNORATI": 'Add to Technorati',
        "CMO_BOOKMARK_YAHOO": 'Add to Yahoo!',
        "MCMS_CLOSE": 'Close'
}

Dependencies

Requires:
YUI:YAHOO, YUI:Connection and YUI:Event
JSON

Facts

- Use the translator to separate your language sentences from your javascript code
- Use the translator to load onDemand certain component's languages when you need it
- Distribute your components in different languages.