angular-i18next

i18next v8.4+ integration with angular v2.0+

Live DEMO

Features
Installation
Usage
Cookbook
Deep integration
In-project testing
Demo
Articles
Support project

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 🍻!

Поддержи проект - угости автора кружечкой пива!

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

Warning:: options in example valid for i18next v20 (Always check latest API options of i18next)

export function appInit(i18next: ITranslationService) {
    return () => i18next.init({
        supportedLngs: ['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 = {
  supportedLngs: ['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.

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)

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:

By default i18next promise will use NativeErrorHandlingStrategy. I18Next would be always resolve succesfully. Error could be get from 'then' handler parameter.
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' }
  }
];

What to do if... ?

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: libs/angular-i18next/src/tests/projectTests

Demo

Live DEMO Demo app source code available here: https://github.com/Romanchuk/angular-i18next-demo

Romanchuk/angular-i18next