Support on Beerpay

Support the project or make a wish

Supporters:
https://beerpay.io/nolazybits/angular-i18n/supports?sort=latest&page=1

Build status

Documentation

angular-i18n is a small Angular module in charge of internationalization and localization.

Dependencies

This module angular-i18n has dependencies resolved with bower on:

sptrinf ("sprintf")

Usage

This module has:

a provider ($i18nProvider)
a factory ($i18n)
a filter (i18n)
a directive (i18n).

Setup

Load the javascript and add the module angular-i18n in the dependencies

<script src="angular-internationalization.js"></script>
<script type="application/javascript">
	var myapp = angular.module('myapp', ['angular-i18n']);
</script>

JSON files

The en-US.json file looks like this

{
    "HELLO_WORLD" : "Hello World",
    "NAME_AGE" : "My name is %s and i am %d years old."
}

The fr-FR.json file looks like this

{
    "HELLO_WORLD" : "Bonjour Monde",
    "NAME_AGE" : "Mon prenom est %s et j'ai %d ans."
}

Provider '$i18n'

Property	Type	Description	Default
allowPartialFileLoading	boolean	Set if you want to be able to load multiple files for a language	`false`
baseHref	string	the base href as found by this library	`''` if not provided by html page
debug	boolean	debug mode	`false`
defaultLanguage	string	The default language to use	`'en-US'`
fallback	JSON	The fallback translation object if the translation files failed to load	`null`
fileURL	string\|Array	Set the template URL(s) where translation files will be loaded from.	```'/i18n/
fileURLLanguageToken	string	The token (string\|regex) to look for in the fileURL which will be replaced with the current language string id (i.e en_US) to be loaded	`/\|LANG\|/`
fileURLPartToken	string	The token (string\|regex) to look for in the fileURL which will be replaced with the current section string id (i.e home) to be loaded	`/\|PART\|/`
language	string	The language to use	`null`
onTranslationFailed	Function	This function is called when the debug mode is on and the translation failed on filter or directives	`null`
useBaseHrefTag	boolean	Should the library prepend the base tag url to the pathLanguageURL (this to help with relative links)	`false`

Example:

    $i18nProvider.allowPartialFileLoading = true;
    $i18nProvider.defaultLanguage = true;
    $i18nProvider.defaultLanguage = 'fr-FR';
    $i18nProvider.fallback = {'welcome': 'falback welcome home'};
    $i18nProvider.fileURL = '/i18n/|LANG|.|PART|.json';
    $i18nProvider.fileURLLanguageToken = /\|LANG\|/;
    $i18nProvider.fileURLPartToken = /\|PART\|/;
    $i18nProvider.language = 'en-GB';
    $i18nProvider.onTranslationFailed = function(lang, translationID, section, placeholders) {...};
    $i18nProvider.useBaseHrefTag = true;

allowPartialFileLoading

Set if you want to be able to load multiple files for a language
type: boolean
default: false

Please check the partial loading section in this documentation.

debug

The debug mode
type: boolean
default: false

defaultLanguage

The default language
type: string
default: 'en-US'

fallback

The fallback translation object if the translation file(s) failed to load
type: JSON
default: null

fileURL

Set the template URL(s) where the translation file(s) will be loaded from
type: string|Array<string>
default: '/i18n/|LANG|.json'

The template URL contains a language token that will be replaced (using regex replace) with the current language id.
The URL can also contain a optional part token needed if you have set allowPartialFileLoading to true
For more information the partial loading section in this documentation.

Note: the language id will have the '-' replaced with '_' (i.e 'en-US' will become en_US).
e.g: if you have a language set to 'en-US' the file /i18n/en_US.json will be loaded.

fileURLLanguageToken

The string or regex to look for which will be replaced with the current language string id (i.e en**_**US) to be loaded
type: string
default: /\|LANG\|/

This is the string or regular expression that will be looked for and replaced with the language id in the path template URL.

Note: the language id will have the '-' replaced with '_' (i.e 'en-US' will become en_US).
So if you have a language set to 'en-US' the file /i18n/en_US.json will be loaded.
If you are using the RegExp object double backslash like new RegExp('\\|LANG\\|');

fileURLPartToken

The string or regex to look for which will be replaced with the current section string id (i.e home) to be loaded
type: string
default: /\|PART\|/

This is the string or regular expression that will be looked for and replaced with the section id in the path template URL.

For more information, please check the partial loading section in this documentation.

language

The explicitly defined language
type: string
default: null

onTranslationFailed

Function called when the debug mode is on and when the translation failed for filters or directives.
Must return a string
type: Function
default: null

example

$i18nProvider.onTranslationFailed = function(lang, translationID, section, placeholders) {
    return '<span style="color: red">translationID</span>
};

The above function returns HTML and no plain text. To have Angular displays the HTML:

with the i18n directive nothing has to be done.
with the i18n filter you will have to do the following:
use your filer inside an element and biding the filter value to ng-bind-html as

So note that the value returned by this function will be $sce.trustAsHtml

Please check the sample app for examples.

useBaseHrefTag

Should the library prepend the base tag url to the fileURL(s) (this to help with relative links)
type: boolean
default: false

Factory '$18n'

The correct language to display is determine by the provider, based on the language of the browser, the default language set or the current language set (if any) as follow: language || $window.navigator.userLanguage || $window.navigator.language || defaultLanguage;

The factory can use all the previous method described in the provider section plus the following:

Property	Type	Description	Default
language	string	The language to use	null
debug	boolean	reference the provider debug property	`false`
onTranslationFailed	Function	Reference the provider onTranslationFailed property	`null`

language

Returns the current language.
type: string
default: null

The returned value check first the language property (can be set at runtime), then browser language and finally the default language (can be set at config and run time)

Events	Description
i18n.file.loaded	Dispatched when a translation file has been loaded

i18n.file.loaded

Dispatched when a translation file has been loaded

The arguments passed are:

lang: the language used
section: the section loaded (if any otherwise 'all')
data: the data received.

Methods	Description
addTranslation(lang, json, section)	add a translation object directly to i18n
removeTranslation(lang, section)	remove a translation object added or loaded to the library
loadTranslation(lang, section)	To explicitly start loading translation file(s) for the current language using the URL and regexp provided at config time
switchTranslation(lang, section)	If you already loaded a language, you can explicitly switch to other and refresh all translations
hasTranslation(lang, section, key)	Check if a translation exist. When omiting the key, check if there is a translation object for this section.
isTranslationLoaded(lang, section)	Check if the translation file has been loaded or the translation object has been added successfully
translate(value, section, placeholders)	Return a promise. THIS IS the function you want to use on the factory

addTranslation(lang: string, json: string, section?: string)

add a translation directly to the library.

lang: the language to add

json: the json string

(section): the section for the language file

This can prove useful if you want to retrieve the translation object(s) yourself and then add them to this library.