#

# Example: Language Resource Bundles

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.

### Defining your Custom Module

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: '../assets/intl',
            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: '../assets/intl',
                modules : {
                    "translator" : {
                        path: 'translator/translator.js',
                        lang: ["en", "fr", "es"]
                    }
                }
            }
        }
    };

    YUI({
        lang:'fr'
    }).use(...);

### What Language Resource Bundles Look Like

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"
            }

        );

    }, "3.10.3");

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.

### Generating Language Resource Bundles

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.

### Accessing Localized Resources In Your Class

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;
        }

        ...
    }

### Specifying the Language for an Instance

We specify the language to use for each instance, using the "lang" configuration property for the instance.

#### An English instance

    YUI({
        lang:"en",
        ...
    }).use("node-base", "translator", function(Y) {
        var translator = new Y.Translator(),
            out = Y.one("#out");

        say("Speaking in: " + Y.Intl.getLang("translator"), out);
        say(translator.hi(), out);
        say(translator.bye(), out);
    });

#### A French YUI Instance

    YUI({
        lang:"fr",
        ...
    }).use("node-base", "translator", function(Y) {
        ...
    });

#### A Spanish YUI Instance

    YUI({
        lang:"es",
        ...
    }).use("node-base", "translator", function(Y) {
        ...
    });

### Modules Shipping With Language Resource Bundles

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.

## Complete Example Source

    <div id="out"></div>

    <script>
    (function() {

        var say = function(msg, node, cls) {
            node.append('<p class="' + cls + '">' + msg + '</p>');
        };

        var appMetaData = {
            myapp: {
                base: '../assets/intl/',
                modules : {
                    "translator" : {
                        path: 'translator/translator.js',
                        lang: ["en", "fr", "es"]
                    }
                }
            }
        };

        YUI({
            lang:"en",
            groups: appMetaData
        }).use("node-base", "translator", function(Y) {
            var translator = new Y.Translator(),
                out = Y.one("#out");

            say("Speaking in: " + Y.Intl.getLang("translator"), out, "speaking");
            say(translator.hi(), out, "word");
            say(translator.bye(), out, "word");
        });

        YUI({
            lang:"fr",
            groups: appMetaData
        }).use("node-base", "translator", function(Y) {
            var translator = new Y.Translator(),
                out = Y.one("#out");

            say("Speaking in: " + Y.Intl.getLang("translator"), out, "speaking");
            say(translator.hi(), out, "word");
            say(translator.bye(), out, "word");
        });

        YUI({
            lang:"es",
            groups: appMetaData
        }).use("node-base", "translator", function(Y) {
            var translator = new Y.Translator(),
                out = Y.one("#out");

            say("Speaking in: " + Y.Intl.getLang("translator"), out, "speaking");
            say(translator.hi(), out, "word");
            say(translator.bye(), out, "word");
        });

    }());
    </script>