@onshape/ng-i18next

ng-i18next - use i18next with Angularjs

Project goal is to provide an easy way to use i18next with AngularJS:

• ng-i18next directive
• i18next filter

First check out the documentation by Jan Mühlemann.

Features

• AngularJS directive
• AngularJS filter
• variable binding (translates again, if variable changes)
• nested translations ($t('hello'); see i18next documentation)
• scope variables in translations (if the translation contains directives of variables like {{hello}}, they'll get compiled)
• sprintf support (directive and provider)
• support for default values to be displayed before i18next engine is initialized

Installation

You can install ng-i18next as a bower dependency:

bower install ng-i18next

Usage

First add

• AngularJS
• i18next
• ng-i18next

to your HTML file. AngularJS and i18next have to be loaded before ng-i18next!

Make sure you require jm.i18next as a dependency of your AngularJS module. Also configurate the provider first:

angular.module('jm.i18next').config(['$i18nextProvider', function ($i18nextProvider) {
	$i18nextProvider.options = {
		lng: 'de',
		useCookie: false,
		useLocalStorage: false,
		fallbackLng: 'dev',
		resGetPath: '../locales/__lng__/__ns__.json',
		defaultLoadingValue: '' // ng-i18next option, *NOT* directly supported by i18next
	};
}]);

For testing purposes set up a server. Don't open your files directly because i18next then fails to load the language files!

For more options visit the i18next documentation.

There are two ways to use ng-i18next:

filter

<p>{{'hello' | i18next}}</p>

=> translates hello

<p>{{hello | i18next}}</p>

=> translates $scope.hello

directive

Basics

<p ng-i18next="hello"></p>

=> translates hello

<p ng-i18next="{{hello}}"></p>

=> translates $scope.hello

<p ng-i18next>hello</p>

=> translates hello (uses the content of the p-tag)

<p ng-i18next>{{hello}}</p>

=> translates $scope.hello (uses the content of the p-tag)

Note, that HTML isn't compiled!

HTML

<p ng-i18next="[html]hello"></p>

=> translates hello and compiles HTML

<p ng-i18next="[html]{{hello}}"></p>

=> translates $scope.hello and compiles HTML

Attributes

<a href="#" ng-i18next="[title]hello">This is a link.</a>

=> translates hello and sets it as the title

<a href="#" ng-i18next="[title]{{hello}}">This is a link.</a>

=> translates $scope.hello and sets it as the title

You can combine both, too!

Attributes + text content

<a href="#" ng-i18next="[title]hello;content"></a>

=> translates hello and sets it as the title => translates content and sets it as the text of the link.

<a href="#" ng-i18next="[title]{{hello}};{{content}}"></a>

=> translates $scope.hello and sets it as the title => translates $scope.content and sets it as the text of the link.

Attributes + HTML content

<a href="#" ng-i18next="[title]hello;[html]content"></a>

=> translates hello and sets it as the title => translates content and compiles the HTML as the content of the link.

<a href="#" ng-i18next="[title]{{hello}};[html]{{content}}"></a>

=> translates $scope.hello and sets it as the title => translates $scope.content and compiles the HTML as the content of the link.

Passing Options

You can also pass options:

<p ng-i18next="[i18next]({lng:'de'})hello"></p>

=> translates hello in German (de)

Passing Options + HTML

Also options work perfectly together with html:

<p ng-i18next="[html:i18next]({lng:'de'})hello"></p>

=> translates hello in German (de) and compiles it to HTML code.

Passing Options - sprintf

You can use i18next sprintf feature:

<p ng-i18next="[i18next]({sprintf:['a','b','c','d']})sprintfString">

where sprintfString could be The first 4 letters of the english alphabet are: %s, %s, %s and %s in your translation file.

Using the directive, postProcess:'sprintf' isn't neccassary. The directive will add it automatically when using sprintf in the options.

---

For more, see examples.

---

Default values while i18next is initializing

i18next supports providing a defaultValue when requesting any translation. But what happens when i18next hasn't been fully initialized yet?

ng-i18next adds a defaultLoadingValue option, which can be provided either in $i18nextProvider.options or with any individual translation request just like you would defaultValue. If i18n strings need to be rendered before i18next is initialized, these special loading values will be used instead.

Default values - Examples

$i18nextProvider.options = {
	/* ... */
	defaultLoadingValue: ''
};

(in template)
<p>{{'hello' | i18next}}</p>

=> displays an empty string (visually nothing) until i18next is initialized, then translates hello

<p>{{'hello' | i18next:{'defaultLoadingValue':'Loading...'} }}</p>

=> displays "Loading..." until i18next is loaded, then translates hello

<p>{{'not-translated-welcome-key' | i18next:{'defaultLoadingValue':'Loading...', 'defaultValue':'Welcome!'} }}</p>

=> displays "Loading..." until i18next is loaded, then translates not-translated-welcome-key with default of "Welcome!" if the key is not defined in your i18n file

---

Contribute

To contribute, you must have:

• Node.js
• bower
• Gulp

installed.

Load all dependencies using npm and bower:

npm install
bower install

Build ng-i18next.js using Gulp:

gulp build

Test ng-i18next.js using Gulp:

gulp test

---

Examples

You can run the examples using:

gulp serve

(note that you have to be in the root directory of this project)

Do not just open the HTML files. That won't work.

---

Supported browsers

ng-i18next is tested with these browsers:

• latest Firefox
• latest Chrome
• IE9 and above

IE8 isn't supported. ng-i18next should work with every browser that is supported by AngularJS.

However, last time we checked, just adding polyfills do the job on IE8.

---

Changelog

For changelog file please see CHANGELOG.md

---

License

MIT License