A localization module for AngularJS.

Table of contents

Getting started

Module setup

The easiest way to install the localize module is via Bower:

You can then include angular-localize after including its dependencies, angular and angular-sanitize:

Translation functions

The localize module requires a map with translation functions.
By convention, this is a global object variable called i18n, which must be available before the Angular application is initialized:

The localize module uses this map to lookup the translation results.
If no matching translation function is found, the key is used as the translation result.

Instead of storing the translation functions in a global object, it's also possible to decorate the i18n service:

The translation functions are expected to return strings with the translation result.
An optional object with dynamic user data is passed as only argument to the translation functions.

How to automatically create the translation functions

grunt-locales, a plugin for the Grunt task runner, provides command-line scripts to automate the creation of the translation functions.

grunt-locales parses localize attributes in HTML files as well as localize method calls in JS files and collects the parsed locale strings in JSON files for translation.
The translated JSON locale files are then compiled into JavaScript files containing the map of translation functions.

To support translation features like pluralization and gender selection, grunt-locales relies on Alex Sexton's MessageFormat library to parse the locale strings and compile the translation functions.

Usage Examples

localize directive

Localize using the element content

Any HTML element which can contain text nodes can be localized simply by adding the localize attribute:

If a translation function for the key "Save the Orangutans!" exists, the localize directive will replace the element content with the result of executing the function.

Localized element content can also contain HTML:

In this case, the key for the translation function is "Save the <strong>Orangutans</strong>!".

The result of the translation function of localizations defined via element content will always be assigned as HTML, but sanitized via angular-sanitize.

Localize using the localize attribute

Instead of the element content, the localization key can also be defined as value of the localize attribute:

If no translation function for the key "Save the Orangutans!" exists, the attribute value will be used as element content.

Localizations defined via localize attribute cannot contain HTML tags, as the translation result will be assigned as text, not as HTML. This limitation enables a slightly faster localization, as no sanitization is required.

Localize with dynamic user data

It's also possible to provide dynamic user data to the translation functions.

The localize directive observes all non-directive data-* attributes and passes them as normalized map of key/value pairs to the translation function:

Whenever is updated, the translation function for "Hello {name}!" gets called with an object, e.g. {name: 'Bob'} as argument and the element content is updated accordingly.

This also works with the localization key as element content, which allows the use of HTML for the translation result:

In this case, all dynamic user data is escaped (HTML special characters are replaced with their respective HTML entity) before it is passed to the translation function.

localize service

The localize service is an equivalent to the localize directive and can be used to generate localized results in situations where the directive cannot be used:

The localize service expects the localization key as first argument and an optional object with user data as second argument.

If the third argument is set to true, the user data will be escaped (HTML special characters are replaced with their respective HTML entity), which allows to output the translation result as HTML, although it still needs to be properly sanitized depending on the security context:

Generally, it is preferable to use the localize directive instead of the service whenever possible, as the directive can determine its security context.


Released under the MIT license.

comments powered by Disqus
This page was last updated over 4 years ago.