angular-i18next v18.0.0
angular-i18next
i18next v8.4+ integration with angular v2.0+
Features
- Native i18next options
- Promise initialization
- i18next plugin support
- Events support
- Namespaces lazy load
- i18next native format support
- document.title localization
- Error handling strategies
- i18next namespaces and scopes (prefixes) for angular modules and components
- AOT support
- Angular Package Format support
Related packages also has implementations for:
- Reactive forms validators localization
- Http error message localizer
Cheers!
Hey dude! Help me out for a couple of :beers:!
Поддержи проект - угости автора кружечкой пива!
Installation
1. Install package
npm install i18next --save
npm install angular-i18next --save
2. Import I18NextModule to AppModule
import { I18NextModule } from 'angular-i18next';
@NgModule({
bootstrap: [ AppComponent ],
declarations: [
AppComponent
],
import: [
I18NextModule.forRoot()
]
})
export class AppModule {}
3. Import I18NextModule.forRoot() to AppModule and setup provider with "init" method (use native options). Angular would not load until i18next initialize event fired
export function appInit(i18next: ITranslationService) {
return () => i18next.init({
whitelist: ['en', 'ru'],
fallbackLng: 'en',
debug: true,
returnEmptyString: false,
ns: [
'translation',
'validation',
'error'
],
});
}
export function localeIdFactory(i18next: ITranslationService) {
return i18next.language;
}
export const I18N_PROVIDERS = [
{
provide: APP_INITIALIZER,
useFactory: appInit,
deps: [I18NEXT_SERVICE],
multi: true
},
{
provide: LOCALE_ID,
deps: [I18NEXT_SERVICE],
useFactory: localeIdFactory
}];
@NgModule({
imports: [
...
I18NextModule.forRoot()
],
providers: [
...
I18N_PROVIDERS,
],
bootstrap: [AppComponent]
})
export class AppModule {
}
Usage
Pipes
Use "i18next" pipe to translate key:
<div>{{ 'test' | i18next }}</div>
Passing "t options":
<div>{{ 'test' | i18next: { count: 5, nsSeparator: '#' } }}</div>
Trigger native i18next format method by using I18NextFormatPipe or I18NextPipe with option 'format':
{{ 'any_key' | i18next | i18nextFormat }}
{{ 'any_key' | i18next: { format: 'cap' } }}
{{ 'any_key' | i18nextCap }}
Note: Using "i18nextCap" you will get the same result as i18next: { format: 'cap' }
REMEMBER that format will not work until you set "interpolation.format" function in i18next options.
I18NextModule has static method static interpolationFormat(customFormat: Function = null): Function
that can be used as default interpolation format function (it provides 'upper', 'cap' and 'lower' formatters). You also can pass your custom function to be called after I18NextModule formatters:
const i18nextOptions = {
whitelist: ['en', 'ru'],
ns: [
'translation',
'validation',
'error',
],
interpolation: {
format: I18NextModule.interpolationFormat((value, format, lng) => {
if(value instanceof Date)
return moment(value).format(format);
return value;
});
// format: I18NextModule.interpolationFormat()
}
};
i18nextEager pipe
This is the impure analog of i18next pipe that is subscribed to language change, it will change string right away to choosen language (without reloading page).
Warning!: Use i18nextEager only in combine with OnPush change detection strategy, or else (default change detection) each pipe will retrigger more than one time (cause of performance issues).
Subscribing to event observables:
this.i18NextService.events.languageChanged.subscribe(lang => {
// do something
})
Add a provider to module/component if you want to prefix child i18next keys:
{
provide: I18NEXT_NAMESPACE,
useValue: 'feature' // set 'feature:' prefix
}
{
provide: I18NEXT_SCOPE,
useValue: 'person' // set 'person.' prefix
}
Since v3.1.0+ it is possible to pass array of namespaces (or scopes). Key would fallback to next namespace in array if the previous failed to resolve.
[feature_validators:key, validators:key]
{
provide: I18NEXT_NAMESPACE,
useValue: ['feature_validators', 'validators']
}
NOTE: Do NOT use default (or custom) i18next delimiters in namespace names.
Document title
If you want to turn on document title localization resolve Title as I18NextTitle
imported from 'angular-i18next':
{
provide: Title,
useClass: I18NextTitle
}
Also you can implement your own Title service with specific behavior. Inject I18NextPipe
(or I18NextService
) to service/component:
import { Injectable, Inject } from '@angular/core';
import { Title, DOCUMENT } from '@angular/platform-browser';
import { I18NextPipe } from 'angular-i18next';
@Injectable()
export class I18NextTitle extends Title {
constructor(private i18nextPipe: I18NextPipe, @Inject(DOCUMENT) doc) {
super(doc);
}
setTitle(value: string) {
return super.setTitle(this.translate(value));
}
private translate(text: string) {
return this.i18nextPipe.transform(text, { format: 'cap'});
}
}
Ways to use I18NextService in your code:
Warning: Injection of I18NextService is possible, but it would not consider I18NEXT_NAMESPACE and I18NEXT_SCOPE providers. There are 2 possible reasons to inject I18NextService: initialization and subscription to its events. In all other cases inject I18NextPipe. 1) Recommended way: Inject via I18NEXT_SERVICE token. By default it will inject instance of I18NextService.
export class AppComponent implements OnInit { constructor(private router: Router, private title: Title, @Inject(I18NEXT_SERVICE) private i18NextService: ITranslationService)
2) Legacy way: Inject via type
export class AppComponent implements OnInit {
constructor(private router: Router,
private title: Title,
private i18NextService: I18NextService)
Error handling
Error handling is now configurable: 1) By default i18next promise will use NativeErrorHandlingStrategy. I18Next would be always resolve succesfully. Error could be get from 'then' handler parameter. 2) Set StrictErrorHandlingStrategy to reject load promises (init, languageChange, loadNamespaces) on first load fail (this was default in v2 but changed to fit native i18next behavior:
`I18NextModule.forRoot({ errorHandlingStrategy: StrictErrorHandlingStrategy })`
Lazy loading
Use I18NEXT_NAMESPACE_RESOLVER in your routes to to load i18next namespace.
Note: It is not neccesary to register lazy loading namespaces in global i18next options.
{
path: 'rich_form',
loadChildren: 'app/features/rich_form_feature/RichFormFeatureModule#RichFormFeatureModule',
data: {
i18nextNamespaces: ['feature.rich_form']
},
resolve: {
i18next: I18NEXT_NAMESPACE_RESOLVER
}
},
Use I18NextService.loadNamespaces() method to load namespaces in code.
Cookbook
i18next plugin support
import { I18NextModule, ITranslationService, I18NEXT_SERVICE } from 'angular-i18next';
// import Backend from 'i18next-xhr-backend'; //for i18next < 20.0.0
import HttpApi from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';
...
i18next.use(HttpApi)
.use(LanguageDetector)
.init(i18nextOptions)
Initialize i18next before angular application
Angular would not load until i18next initialize event fired
export function appInit(i18next: ITranslationService) {
return () => i18next.init();
}
export function localeIdFactory(i18next: ITranslationService) {
return i18next.language;
}
export const I18N_PROVIDERS = [
{
provide: APP_INITIALIZER,
useFactory: appInit,
deps: [I18NEXT_SERVICE],
multi: true
},
{
provide: LOCALE_ID,
deps: [I18NEXT_SERVICE],
useFactory: localeIdFactory
}];
Document title update on language or route change
export class AppComponent implements OnInit {
constructor(private router: Router,
private title: Title,
@Inject(I18NEXT_SERVICE) private i18NextService: ITranslationService) {
// page title subscription
// https://toddmotto.com/dynamic-page-titles-angular-2-router-events#final-code
this.router.events
.filter(event => event instanceof NavigationEnd)
.map(() => this.router.routerState.root)
.map(route => {
while (route.firstChild) route = route.firstChild;
return route;
})
.filter(route => route.outlet === 'primary')
.mergeMap(route => route.data)
.subscribe((event) => this.updatePageTitle(event['title']));
}
ngOnInit() {
this.i18NextService.events.languageChanged.subscribe(lang => {
let root = this.router.routerState.root;
if (root != null && root.firstChild != null) {
let data: any = root.firstChild.data;
this.updatePageTitle(data && data.value && data.value.title);
}
});
}
updatePageTitle(title: string): void {
let newTitle = title || 'application_title';
this.title.setTitle(newTitle);
}
}
Routes example:
const appRoutes: Routes = [
{
path: 'error',
component: AppErrorComponent,
data: { title: 'error:error_occured' }
},
{
path: 'denied',
component: AccessDeniedComponent,
data: { title: 'error:access_denied' }
}
];
New angular version released, but angular-i18next is not released YET!!!
Angular releases mostly don't break angular-i18next, but we cannot tell ahead that current version of angular-i18next
will work correctly with latest angular version.
You can override an angular-i18next peerDependencies
in your package.json
on your own risk:
"overrides": {
"angular-i18next": {
"@angular/common": "*",
"@angular/core": "*",
"@angular/platform-browser": "*"
}
}
Deep integration
List of packages to integrate angular and i18next more deeply:
- angular-validation-message - angular reactive form validators integration (and angular-validation-message-i18next is i18next bridge to it). It gives you possibility to localize form validators and it automatically puts localized validator error message to markup (if there is one).
- angular-i18next-error-interceptor - allows you to set default errot messages for non-200 http status responses. So if the back-end didn't specify { message: 'some error' } in a response (sort of contract with our backend) interceptor will check response status code and will fill { message: 'Server is not available. Please try again.' }. Also package includes pipe where you can pass HttpErrorResponse and it will return error message whenever it's back-end message or our localized message.
In-project testing
You might want to unit-test project components that are using i18next pipes
Example tests setup: /tests/projectTests/projectTests.spec.ts
Demo
Live DEMO Demo app source code available here: https://github.com/Romanchuk/angular-i18next-demo
Articles
7 months ago
7 months ago
7 months ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
2 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
8 years ago
8 years ago