isabella232 / ng-i18next

translation for AngularJS using i18next

ng-i18next - use i18next with AngularJS

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

• ng-i18next directive
• i18next filter

First check out the documentation by Jan Mühlemann.

Features

• AngularJS provider, directive and filter
• variable binding (translates again when 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)

Installation Bower

You can install ng-i18next as a bower dependency:

bower install ng-i18next

Installation npm

You can install ng-i18next as a npm dependency:

npm install ng-i18next

Upgrading from <=0.5.5

You will need to

1. Move initialization of i18next from the ng-i18next provider within Angular to i18next natively before booting Angular
2. Change translations using the $i18next provider in you Angular code. From $i18next('localeKey') to $i18next.t('localeKey')

Usage

First add

• AngularJS >=1.5.0
• ngSanitize
• i18next
• i18next-xhr-backend or a backend of your choice to load locales.
• ng-i18next

to your HTML file. AngularJS, ngSanitize, i18next, and i18next-xhr-backend have to be loaded before ng-i18next!

Before booting angular use i18next configuration system to configure and load your localization resources. Refer to i18next configuration reference.

window.i18next
	.use(window.i18nextXHRBackend);

window.i18next.init({
	debug: true,
	lng: 'de', // If not given, i18n will detect the browser language.
	fallbackLng: 'dev', // Default is dev
	backend: {
		loadPath: '../locales/{{lng}}/{{ns}}.json'
	},
	useCookie: false,
	useLocalStorage: false
}, function (err, t) {
	console.log('resources loaded');
});

There are three 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.

provider

=> translates hello

angular
	.module('MyApp', ['jm.i18next'])
	.controller('MyProviderCtrl', function ($scope, $i18next) {
		'use strict';
		$scope.hello = $i18next.t('hello');
});

=> translates hello with translate options

$scope.sprintf = $i18next.t('both.sprintf', { postProcess: 'sprintf', sprintf: ['a', 'b', 'c', 'd'] });

=> translates copyright label and use interpolation to add the year

locale

{
    "copyrightLabel": "Copyright __year__ Acme, Inc. All rights reserved",
}

JavaScript

$i18next.t('copyrightLabel', { year: this.$window.moment().year() });

Results

Copyright 2016 Acme, Inc. All rights reserved

---

For more, see examples.

There are two ways to run the examples:

gulp serve

Run this inside your ng-i18next directory. (This requires you to have NodeJS and gulp to be installed.)

---

Contribute

To contribute, you must have:

• Node.js
• Gulp
• bower
• TypeScript
• typings

installed.

Load all dependencies using npm, bower and typings:

npm install
bower install
typings 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