An implementation of angular translate for Angular 2.
Simple example using ng2-translate: https://github.com/ocombe/ng2-play/tree/ng2-translate
Get the complete changelog here: https://github.com/ocombe/ng2-translate/releases
First you need to install the npm module:
npm install ng2-translate --save
If you use SystemJS to load your files, you might have to update your config with this if you don't use defaultJSExtensions: true
:
System.config({
packages: {
"/ng2-translate": {"defaultExtension": "js"}
}
});
Finally, you can use ng2-translate in your Angular 2 project (make sure that you've loaded the angular2/http bundle as well).
It is recommended to use TRANSLATE_PROVIDERS
in the bootstrap of your application and to never add TranslateService
to the "providers" property of your components, this way you will keep it as a singleton.
TRANSLATE_PROVIDERS
provides a default configuration for the static translation file loader.
If you add TranslateService
to the "providers" property of a component it will instantiate a new instance of the service that won't be initialized with the language to use or the default language.
import {HTTP_PROVIDERS} from 'angular2/http';
import {Component, Injectable, provide} from 'angular2/core';
import {TRANSLATE_PROVIDERS, TranslateService, TranslatePipe, TranslateLoader, TranslateStaticLoader} from 'ng2-translate/ng2-translate';
import {bootstrap} from 'angular2/platform/browser';
bootstrap(AppComponent, [
HTTP_PROVIDERS,
// not required, but recommended to have 1 unique instance of your service
TRANSLATE_PROVIDERS
]);
@Component({
selector: 'app',
template: `
<div>{{ 'HELLO' | translate:{value: param} }}</div>
`,
pipes: [TranslatePipe]
})
export class AppComponent {
param: string = "world";
constructor(translate: TranslateService) {
var userLang = navigator.language.split('-')[0]; // use navigator lang if available
userLang = /(fr|en)/gi.test(userLang) ? userLang : 'en';
// this language will be used as a fallback when a translation isn't found in the current language
translate.setDefaultLang('en');
// the lang to use, if the lang isn't available, it will use the current loader to get them
translate.use(userLang);
}
}
For now, only the static loader is available. You can configure it like this during bootstrap or in the providers
property of a component:
bootstrap(AppComponent, [
HTTP_PROVIDERS,
provide(TranslateLoader, {
useFactory: (http: Http) => new TranslateStaticLoader(http, 'assets/i18n', '.json'),
deps: [Http]
}),
// use TranslateService here, and not TRANSLATE_PROVIDERS (which will define a default TranslateStaticLoader)
TranslateService
]);
For Ionic 2 here is a complete bootstrap with configuration:
import {provide} from 'angular2/core';
import {TranslateService, TranslateLoader, TranslateStaticLoader} from 'ng2-translate/ng2-translate';
@App({
templateUrl: '....',
config: {},
providers: [
provide(TranslateLoader, {
useFactory: (http: Http) => new TranslateStaticLoader(http, 'assets/i18n', '.json'),
deps: [Http]
}),
TranslateService
]
})
Then put your translations in a json file that looks like this (for en.json
):
{
"HELLO": "hello {{value}}"
}
An then you can get new translations like this:
translate.getTranslation(userLang);
But you can also define your translations manually instead of using getTranslation
:
translate.setTranslation('en', {
"HELLO": "hello {{value}}"
});
-
currentLang
: The lang currently used -
currentLoader
: An instance of the loader currently used (static loader by default) -
onLangChange
: An EventEmitter to listen to lang change events. ALangChangeEvent
is an object with the propertieslang: string
&translations: any
(an object containing your translations).example:
onLangChange.subscribe(event: LangChangeEvent) => { // do something });
setDefaultLang(lang: string)
: Sets the default language to use as a fallbackuse(lang: string): Observable<any>
: Changes the lang currently usedgetTranslation(lang: string): Observable<any>
: Gets an object of translations for a given language with the current loadersetTranslation(lang: string, translations: Object)
: Manually sets an object of translations for a given languagegetLangs()
: Returns an array of currently available langsget(key: string|Array<string>, interpolateParams?: Object): Observable<string|Object>
: Gets the translated value of a key (or an array of keys)instant(key: string|Array<string>, interpolateParams?: Object): string|Object
: Gets the instant translated value of a key (or an array of keys)set(key: string, value: string, lang?: string)
: Sets the translated value of a keyreloadLang(lang: string): Observable<string|Object>
: Calls resetLang and retrieves the translations object for the current loaderresetLang(lang: string)
: Removes the current translations for this lang. /!\ You will have to calluse
,reloadLang
orgetTranslation
again to be able to get translations
If you want to write your own loader, you need to create a class that implements TranslateLoader
.
The only required method is getTranslation
that must return an Observable
. If your loader is synchronous, just use Observable.of
to create an observable from your static value.
class CustomLoader implements TranslateLoader {
getTranslation(lang: string): Observable<any> {
return Observable.of({"KEY": "Value"});
}
}
Once you've defined your loader, you can provide it during bootstrap or in the providers
property of a component:
provide(TranslateLoader, {useClass: CustomLoader})
You can setup a provider for MissingTranslationHandler
in the bootstrap of your application (recommended), or in the providers
property of a component.
It will be called when the requested translation is not available.
The only required method is handle
where you can do whatever you want. If this method returns a value or an observable (that should return a string), then this will be used.
Just don't forget that it will be called synchronously from the instant
method.
Create a Missing Translation Handler
import {MissingTranslationHandler} from 'ng2-translate/ng2-translate';
export class MyMissingTranslationHandler implements MissingTranslationHandler {
handle(key: string) {
return 'some value';
}
}
Setup the Missing Translation Handler in bootstrap (recommended) or in the providers
property of a component
provide(MissingTranslationHandler, { useClass: MyMissingTranslationHandler })
You can call the TranslatePipe with some optional parameters that will be transpolated into the translation for the given key.
Example:
<p>Say {{ 'HELLO' | translate:{value: "world"} }}</p>
With the given translation: "HELLO": "hello {{value}}"
.
-
interpolate(expr: string, params?: any): string
: Interpolates a string to replace parameters.This is a {{ key }}
==>This is a value
withparams = { key: "value" }
-
getValue(target: any, key: stirng): any
: Gets a value from an object by composed keyparser.getValue({ key1: { keyA: 'valueI' }}, 'key1.keyA') ==> 'valueI'