This example shows how you can define language resource bundles for your custom module implementations; it also illustrates how YUI Loader can load the correct bundle based on the language you've chosen for your YUI instance.
We use Loader's groups support to add a custom module called "translator" under the group "myapp". The "lang" property in the module's metadata specifies which set of languages it supports.
``` var appMetaData = { myapp: { base: '{{componentAssets}}', modules : { "translator" : { path: 'translator/translator.js', lang: ["en", "fr", "es"] } } } }; YUI({ lang:'fr', groups: appMetaData }).use(...); ```NOTE: Since this example is hosted on a page with other YUI instances, we don't want to pollute their configuration, so we just pass our `groups: appMetaData` configuration property to each YUI instance we create as shown above.
If you own all YUI instances on the page, you can use the global `YUI_Config` variable to define a global configuration for all YUI instances on the page, to avoid passing the same meta-data to all your instances as shown below:
``` var YUI_Config = { groups: { myapp: { base: '{{componentAssets}}', modules : { "translator" : { path: 'translator/translator.js', lang: ["en", "fr", "es"] } } } } }; YUI({ lang:'fr' }).use(...); ```The language resource bundles for any module follows the pattern below:
``` YUI.add("lang/translator_fr", function(Y) { Y.Intl.add( "translator", // Associated Module "fr", // BCP 47 Language Tag { // Translated String Key/Value Pairs hello:"Bonjour", goodbye: "Au revoir" } ); }, "{{{yuiVersion}}}"); ```The `"lang/[for-module]_[lang]"` passed to `YUI.add` is the default module name used for language resource bundles, and the `Y.Intl.add` method is used to register the string name/value pair hash for a given module and language combination.
Shifter will handle the creation of the boiler plate code shown above, from the raw language files found in the module's `src/[module]/lang` subdirectory. The raw files under the `lang` directory contain just the string name/value pairs for each language.
Provide the raw string name/value pairs in the `src/[component]/lang` subdirectory in your component's source area:
``` // Contents of the raw src/[component]/lang/[component]_fr.js file { hello:"Bonjour", goodbye: "Au revoir" } ```And whenever you build your component code, the language resource bundles will be built and deployed too.
You can checkout the YUI 3 Source Code and see the source code and build configuration files for the "console" and "datatype-date-format" modules to see a concrete example of this.
The Translator class implementation gets access to the localized strings by using `Y.Intl.get`, passing in the module name whose strings we need access to:
``` function Translator() { // Get localized strings in the current language this._strs = Y.Intl.get("translator"); } Translator.prototype = { hi : function() { return this._strs.hello; }, bye : function() { return this._strs.goodbye; } ... } ```We specify the language to use for each instance, using the "lang" configuration property for the instance.
As mentioned above, the `datatype` module (specifically the `datatype-date-format` module) and `console` are shipped with language resource bundles. Datatype ships with over 50 different languages supported, and Console ships with en and es language resource bundles, mainly as a demonstration of how language resource bundles are defined and used for Widget development.