ngx-easy-i18n-js

December 18, 2023 · View on GitHub

Pure version angular for internalization (i18n).

Translations are static. If you change language you must refresh the page or use bootstrap extension.

Use EasyI18 Js library https://github.com/gabrie-allaigre/easy-i18n-js

Download and Installation

Install using npm:

npm install easy-i18n-js @ngx-easy-i18n-js/core --save

Open angular.json and under allowedCommonJsDependencies add:

"allowedCommonJsDependencies": [
"easy-i18n-js"
]

Usage in app.module.ts, add imports

import localeFr from '@angular/common/locales/fr';
import localeEn from '@angular/common/locales/en';

imports: [
  EasyI18nModule.forRoot({
    options: {
      logging: false
    },
    ngLocales: {
      'fr': localeFr,
      'en': localeEn,
    },
    defaultLanguage: 'en-US'
  })
]

Configuration

export interface EasyI18nModuleConfig {
  // Options fo easy i18 js library
  options?: EasyI18nOptions;
  // Use specific loader
  loader?: Provider;
  // Add Angular locale <code>import localeFr from '@angular/common/locales/fr';</code>
  ngLocales?: { [key: string]: any; };
  // Use browser language
  useBrowserLanguage?: boolean;
  // Default fallback language use if current language not found
  defaultLanguage?: string;
  // <code>exact</code> only fr-FR, <code>minimum</code> only fr, <code>all</code> fr-FR and fr
  discover?: 'exact' | 'minimum' | 'all';
}

In child module

imports: [
  EasyI18nModule
]

For change current locale use EasyI18nService

export class MyComponent {

  constructor(
    private easyI18nService: EasyI18nService
  ) {
  }

  public doChangeLanguage(locale: string): void {
    this.easyI18nService.registerCulture('fr');
  }
}

Force reload if change culture

 this.easyI18nService.registerCulture('fr', { reload: true });

Locale pipes

In HTML, uses locales pipes to get dates, numbers in locale format

pipe	description	example
`localeDate`	Same as `date`	`{{ mydate \| localeDate:'short' }}`
`localeNumber`	Same as `number`	`{{ mydate \| localeNumber }}`
`localeCurrency`	Same as `currency`	`{{ mydate \| localeCurrency }}`
`localePercent`	Same as `percent`	`{{ mydate \| localePercent }}`

Translate

Main function for translate your language keys

HTML file

In HTML template, with pipe, parameter is TrOptions

{{ 'hello' | tr }}
{{ 'hello_with_genre' | tr: { gender: 'male' } }}
{{ 'My name is {}' | tr: { args: ['Gabriel'] } }}

TrOptions arguments

Name	type	example
args	`string[]`	`['Gabriel', '20']`
namedArgs	`{ [key: string]: string; } }`	`{ name : 'Gabriel', age : '20' }`
namespace	`string`	`'common'`
gender	`'male' \| 'female' \| 'other'`	`gender: 'other'`

Directives

There are 2 differents directives

First is simple, translate [tr]

Directive	description	example
`tr`	Active directive translate	`<span tr>hello</span>`
`trNamespace`	Add namespace	`<span tr trNamespace="common">hello</span>`
`trKey`	Set key (if empty use content)	`<span tr trKey="hello" trNamespace="common"></span>`
`trGender`	Gender	`<span tr trGender="male">hello_with_genre</span>`
`trArgs`	Arguments	`<span tr [trArgs]="['Gabriel']">hello</span>`
`trNamedArgs`	Named arguments	`<span tr [trNamedArgs]="{ name: 'Gabriel' }">hello</span>`

Second, use HTML named arguments [trContent], replace {namedArg} with child element *trElement

Directive	description
`trContent`	Active content directive translate, get a key
`trNamespace`	Add namespace
`trGender`	Gender
`trArgs`	Arguments
`trNamedArgs`	Named arguments
`demarc`	Change token start, end identifier

Examples

<!-- "hello_name": "My name is {name}" -->
<div trContent="hello_name">
    <span *trElement="'name'" style="color: red; font-size: 2rem; font-weight: bold">Gabriel</span>
</div>


<div trContent="My name is {name} and I live in {country}" style="color: blue;">
    <span *trElement="'name'" style="color: red; font-size: 2rem; font-weight: bold">Gabriel</span>
    <span *trElement="'country'">{{ var_country }}</span>
</div>

Typescript file

You can use extension methods of [String], you can also use tr() as a static function.

In typescript file, there is no need to inject EasyI18nService

'hello'.tr();
'hello_with_genre'.tr({ gender: 'male' });
tr('hello');
tr('hello_with_genre', { gender: 'male' });

Translate Plural

You can translate with pluralization. To insert a number in the translated string, use {}.

HTML file

In HTML template, with pipe, first parameter is number and second PluralOptions

{{ 'money' | plural:10 }}
{{ 'money_with_args' | plural:3: { args: ['Gabriel'] } }}

PluralOptions arguments

Name	type	example
args	`string[]`	`['Gabriel', '20']`
namedArgs	`{ [key: string]: string; } }`	`{ name : 'Gabriel', age : '20' }`
namespace	`string`	`'common'`
name	`string`	`money`
numberFormatterFn	`(value: number) => string`	`(value) => value.Precision(3)`
gender	`'male' \| 'female' \| 'other'`	`gender: 'other'`

Directives

There are 2 different directives

First is simple, translate plural [plural]

Directive	description	example
`plural`	Active directive translate	`<span [plural]="10">money</span>`
`pluralNamespace`	Add namespace	`<span [plural]="100" pluralNamespace="common">money</span>`
`pluralKey`	Set key (if empty use content)	`<span [plural]="100" pluralKey="money" pluralNamespace="common"></span>`
`pluralGender`	Gender	`<span [plural]="1" pluralGender="male">money_with_genre</span>`
`pluralArgs`	Arguments	`<span [plural]="5" [pluralArgs]="['Gabriel']">money</span>`
`pluralNamedArgs`	Named arguments	`<span [plural]="13" [pluralNamedArgs]="{ name: 'Gabriel' }">money</span>`
`pluralName`	Name value	`<span [plural]="4" pluralName="value">money</span>`
`pluralNumberFormatterFn`	Formatter function	`<span [plural]="10000" [pluralNumberFormatterFn]="myFn">money</span>`

Second, use HTML named arguments [pluralContent], replace {namedArg} with child element *pluralElement

Directive	description
`pluralContent`	Active content directive translate, get a key
`pluralValue`	Active content directive translate, get a value
`pluralNamespace`	Add namespace
`pluralGender`	Gender
`pluralArgs`	Arguments
`pluralNamedArgs`	Named arguments
`pluralName`	Name value
`pluralNumberFormatterFn`	Formatter function
`demarc`	Change token start, end identifier

Examples

<!-- "money_content": { 
    "zero": "{name} not have money",
    "one": "{name} have {money} dollar",
    "two": "{name} have {money} dollars",
    "many": "{name} have {money} dollars",
    "other": "{name} have {money} dollars"
} -->
<div pluralContent="money_content" [pluralValue]="var_money" class="fst-italic text-gray-500">
    <span *pluralElement="'name'" style="color: red; font-size: 2rem; font-weight: bold">Gabriel</span>
    <span *pluralElement="'money'" style="color: blueviolet; font-weight: bold"
          [style.font-size]="(var_money / 10) + 'vw'">{{ var_money }}</span>
</div>

Typescript file

You can use extension methods of [String], you can also use plural() as a static function.

In typescript file, there is no need to inject EasyI18nService

'money_args'.plural(0, { args: ['Gabriel'] });
'money_args'.plural(1.5, { args: ['Gabriel'] });
plural('money_args', { args: ['Gabriel'] });

Store

Default store is EmptyEasyI18nStore

Use localStorage store, usage in app.module.ts, add provider

providers: [
  {
    provide: EasyI18nStore,
    useFactory: () => new LocalStorageEasyI18nStore('current-lang')
  }
]

Add HttpLoader

Standard

Load messages with HttpClient

Install using npm:

npm install @ngx-easy-i18n-js/http-loader --save

Usage in app.module.ts, add provider

providers: [
  {
    provide: EasyI18nLoader,
    deps: [HttpClient],
    useFactory: (httpClient: HttpClient) => new HttpEasyI18nLoader(httpClient)
  }
]

Change prefix or suffix with options

new HttpEasyI18nLoader(httpClient, {
  prefix: 'assets/',
  suffix: '.json5'
});

new HttpEasyI18nLoader(httpClient, {
  prefix: ['assets/common/i18n', 'assets/i18n'],
  suffix: '.json5'
});

Scoped loader

Load multiples files with scope

Usage in app.module.ts, add provider

providers: [
  {
    provide: EasyI18nLoader,
    deps: [HttpClient],
    useFactory: (httpClient: HttpClient) => new ScopedHttpEasyI18nLoader(httpClient, [
      { prefix: `/assets/i18n/` },
      { prefix: ['assets/common/i18n', 'assets/i18n/common'], scope: 'common' },
      { prefix: `/assets/i18n/errors/`, scope: 'errors' }
    ])
  }
]

{{ 'common.save' | tr }}
{{ 'errors.internal_server_error' | tr }}

Change suffix

new ScopedHttpEasyI18nLoader(httpClient, [
    { prefix: `/assets/i18n/` }
  ], {
  suffix: '.json5'
});

Append scoped loader for lazy routes

const routes: Routes = [
  {
    path: 'login',
    loadChildren: () => import('./login/login.module').then(m => m.LoginModule),
    canActivate: [
      appendScopedHttpEasyI18nLoader([
        { prefix: `/assets/i18n/login/`, scope: 'login' }
      ])
    ]
  }
];

Add Bootstrap

Bootstrap application, refresh application when culture change without reload page

Install using npm:

npm install @angular/cdk @ngx-easy-i18n-js/bootstrap --save

Usage

imports: [
  EasyI18nBootstrapModule.forRoot({
    bootstrap: AppComponent
  })
]

bootstrap: [EasyI18nBootstrapComponent]

And in index.html, replace <app-root></app-root> by <ngx-easy-i18n></ngx-easy-i18n>

For custom loading component

imports: [
  EasyI18nBootstrapModule.forRoot({
    bootstrap: AppComponent,
    loadingComponent: MyLoadingComponent
  })
]

bootstrap: [EasyI18nBootstrapComponent]