<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Example: Language Resource Bundles</title>
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic">
<link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css">
<link rel="stylesheet" href="../assets/css/main.css">
<link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
<link rel="shortcut icon" type="image/png" href="../assets/favicon.png">
<script src="../../build/yui/yui-min.js"></script>
</head>
<body>
<!--
<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
-->
<div id="doc">
<div id="hd">
<h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1>
</div>
<h1>Example: Language Resource Bundles</h1>
<div class="yui3-g">
<div class="yui3-u-3-4">
<div id="main">
<div class="content"><style scoped>
#out .word {
margin:0.3em 0.3em 0.3em 1em;
}
#out .speaking {
font-size:108%;
color:#00aa00;
margin-top:1em;
margin-bottom:1em;
}
</style>
<div class="intro">
<p>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.</p>
</div>
<div class="example">
<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>
</div>
<h3>Defining your Custom Module</h3>
<p>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.</p>
<pre class="code prettyprint">var appMetaData = {
myapp: {
base: '../assets/intl',
modules : {
"translator" : {
path: 'translator/translator.js',
lang: ["en", "fr", "es"]
}
}
}
};
YUI({
lang:'fr',
groups: appMetaData
}).use(...);</pre>
<p>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 <code>groups: appMetaData</code> configuration property to each YUI instance we create as shown above.</p>
<p>If you own all YUI instances on the page, you can use the global <code>YUI_Config</code> 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:</p>
<pre class="code prettyprint">var YUI_Config = {
groups: {
myapp: {
base: '../assets/intl',
modules : {
"translator" : {
path: 'translator/translator.js',
lang: ["en", "fr", "es"]
}
}
}
}
};
YUI({
lang:'fr'
}).use(...);</pre>
<h3>What Language Resource Bundles Look Like</h3>
<p>The language resource bundles for any module follows the pattern below:</p>
<pre class="code prettyprint">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");</pre>
<p>The <code>"lang/[for-module]_[lang]"</code> passed to <code>YUI.add</code> is the default module name used for language resource bundles, and the <code>Y.Intl.add</code> method is used to register the string name/value pair hash for a given module and language combination.
<h3>Generating Language Resource Bundles</h3>
<p><a href="http://yui.github.com/shifter">Shifter</a> will handle the creation of the boiler plate code shown above, from the raw language files found in the module's <code>src/[module]/lang</code> subdirectory. The raw files under the <code>lang</code> directory contain just the string name/value pairs for each language.</p>
<p>Provide the raw string name/value pairs in the <code>src/[component]/lang</code> subdirectory in your component's source area:</p>
<pre class="code prettyprint">// Contents of the raw src/[component]/lang/[component]_fr.js file
{
hello:"Bonjour",
goodbye: "Au revoir"
}</pre>
<p>And whenever you build your component code, the language resource bundles will be built and deployed too.</p>
<p>You can checkout the <a href="http://github.com/yui/yui3"></a>YUI 3 Source Code</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.</p>
<h3>Accessing Localized Resources In Your Class</h3>
<p>The Translator class implementation gets access to the localized strings by using <code>Y.Intl.get</code>, passing in the module name whose strings we need access to:</p>
<pre class="code prettyprint">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;
}
...
}</pre>
<h3>Specifying the Language for an Instance</h3>
<p>We specify the language to use for each instance, using the "lang" configuration property for the instance.</p>
<h4> An English instance</h4>
<pre class="code prettyprint">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);
});</pre>
<h4>A French YUI Instance</h4>
<pre class="code prettyprint">YUI({
lang:"fr",
...
}).use("node-base", "translator", function(Y) {
...
});</pre>
<h4>A Spanish YUI Instance</h4>
<pre class="code prettyprint">YUI({
lang:"es",
...
}).use("node-base", "translator", function(Y) {
...
});</pre>
<h3>Modules Shipping With Language Resource Bundles</h3>
<p>As mentioned above, the <code>datatype</code> module (specifically the <code>datatype-date-format</code> module) and <code>console</code> 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.</p>
<h2>Complete Example Source</h2>
<pre class="code prettyprint"><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></pre>
</div>
</div>
</div>
<div class="yui3-u-1-4">
<div class="sidebar">
<div class="sidebox">
<div class="hd">
<h2 class="no-toc">Examples</h2>
</div>
<div class="bd">
<ul class="examples">
<li data-description="How to create components which use language resource bundles.">
<a href="intl-basic.html">Language Resource Bundles</a>
</li>
</ul>
</div>
</div>
<div class="sidebox">
<div class="hd">
<h2 class="no-toc">Examples That Use This Component</h2>
</div>
<div class="bd">
<ul class="examples">
<li data-description="Formatting dates into strings using pre-packaged language resource bundles.">
<a href="../datatype/datatype-dateformat-lang.html">Formatting Dates Using Language Resource Bundles</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>
<script>
YUI.Env.Tests = {
examples: [],
project: '../assets',
assets: '../assets/intl',
name: 'intl-basic',
title: 'Language Resource Bundles',
newWindow: '',
auto: false
};
YUI.Env.Tests.examples.push('intl-basic');
YUI.Env.Tests.examples.push('datatype-dateformat-lang');
</script>
<script src="../assets/yui/test-runner.js"></script>
</body>
</html>