@onshape/ng-i18next
v0.3.17-1
Published
AngularJS filter and directive for i18next (i18next by Jan Mühlemann)
Downloads
86
Maintainers
Keywords
Readme
ng-i18next - use i18next with Angularjs
Project goal is to provide an easy way to use i18next with AngularJS:
ng-i18next
directivei18next
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:
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