Jump to:

• The Localization Directive
• Adding Custom Localization to Your Plugins

Internet users speaks many languages and a top-tier content management has to be able to support any language you might throw at it. Because of this, we built PencilBlue, from the ground up, to be localizable. Any static content on your site can be easily set up to work in multiple languages.

Localization is automatically driven by the user's preferred language in their browser. As long as a matching language definition exists, that language will be displayed in the user's browser.

To localize a string in HTML templates, the ^loc_[localization_key]^ directive is used. PencilBlue comes with a core localization setup in the /public/localization/ folder. These are the default keys that can be called with the localization directive.

For example, to display the localized text for "left," "right," and "center," the following localization directives would be used.

<div>^loc_LEFT^</div>
<div>^loc_RIGHT^</div>
<div>^loc_CENTER^</div>

The resulting US English output, loaded from /public/localization/en-us.js, would be:

Left
Right
Center

Any plugin can define it's own localization keys and values in any number of languages. To add a language to a plugin, place a JSON file in the plugin's /public/localization/ folder. For example, the US English localization file for the Portfolio plugin is located at /plugins/portfolio/public/localization/en-us.json.

A plugin localization JSON consists of localization keys and their values. Here's the content of the Portfolio theme's US English localization file:

{
    "RELATED_ARTICLES": "Related Articles",
    "RETURN_TO": "Return to the",
    "BLOG": "blog",
    "HOME_PAGE_SETTINGS": "Home page settings",
    "HOME_LAYOUT": "Home page layout",
    "HOME_MEDIA": "Home page media",
    "HERO_IMAGE": "Hero image",
    "CALLOUTS": "Callouts",
    "CALLOUT_HEADLINE": "Callout headline",
    "CALLOUT_LINK": "Callout link",
    "CALLOUT_COPY": "Callout copy"
}

The localization files of plugins are automatically merged into PencilBlue's localization service on startup. Keys are overridden with the same hierarchy as templates. You can place a custom localization in any HTML template with the same ^loc_[localization_key]^ directive used for PencilBlue's default localization keys.

Languages differ in terms of the ordering of subjects and predicate or nouns and adjectives. In order to provide support for these differences the Localization service allows for keys to be patterned. You could have a key:

{
  "PATTERN_KEY": "This is a string %s.  This is a number %d.  This is a JSON value %j"
}

Inside of a controller this key can be easily localized as shown below:

MyController.prototype.render = function(cb) {
  
  var str = 'hello';
  var num = 67.8;
  var json = { a: 'a', b: 2, c: false};
  var text = this.ls.get('PATTERN_KEY', str, num, json);
  this.ts.registerLocal('text', text);
  ...
};

The above would render the text as: This is a string hello. This is a number 67.8. This is a JSON value { "a": "a", "b": 2, "c": false}