README

@nwx/i18n

A simple translation module for Angular applications

How to install

npm i @nwx/i18n |OR| yarn add @nwx/i18n

How to use

// In your environment{prod,staging}.ts

import { AppCfg, TargetPlatform, HttpMethod } from '@nwx/cfg';
import { LogLevels } from '@nwx/logger';

export const environment: AppCfg = {
  // app name
  appName: 'Neekware',
  // target (browser, mobile, desktop)
  target: TargetPlatform.web,
  // production, staging or development
  production: false,
  // one or more app specific field(s)
  log: {
    // Log level, (default = none)
    level: LogLevels.info
  },
  i18n: {
    // available languages
    availableLanguages: {
      en: {
        name: 'English',
        locale: '@angular/common/locales/en',
        localeExtra: '@angular/common/locales/extra/en'
      },
      fr: {
        name: 'Français',
        locale: '@angular/common/locales/fr',
        localeExtra: '@angular/common/locales/extra/fr'
      },
      de: {
        name: 'Deutsch',
        locale: '@angular/common/locales/de',
        localeExtra: '@angular/common/locales/extra/de'
      }
    },
    // enabled languages (iso list)
    enabledLanguages: [
      // order is important
      'en',
      'fr'
    ],
    // cache busting hash
    // bump when you change any file in /assets/i18n/*.json
    cacheBustingHash: 'v1.0.0'
  }
};

// In your app.module.ts

import { CfgModule } from '@nwx/cfg';
import { LoggerModule } from '@nwx/logger';
import { I18nModule } from '@nwx/i18n';

import { environment } from '../environments/environment';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    CfgModule.forRoot(environment), // make the environment injectable
    LoggerModule,
    I18nModule.forRoot()
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

// In your app.component.ts
import { Component } from '@angular/core';
import { CfgService, DefaultCfg } from '@nwx/cfg';
import { LogService } from '@nwx/logger';
import { I18nService } from '@nwx/i18n';

@Component({
  selector: 'app-root',
  template: `<h1>{{'COMMON.WELCOME' | translate}} to {{ title }}!</h1>`
})
export class AppComponent {
  title = 'Neekware';
  constructor(public cfg: CfgService, public log: LogService, public i18n: I18nService) {
    this.title = this.cfg.options.appName;
    this.i18n.setCurrentLanguage('fr'); // set language to French
    this.log.info('AppComponent loaded ...');
  }
}

Include your translated files in the /assets/i18n directory of your application.

/assets/i18n/en.json

{
  "COMMON.WELCOME": "Welcome",
  "COMMON.ABOUT": "About"
}

/assets/i18n/fr.json

{
  "COMMON.WELCOME": "Bienvenue",
  "COMMON.ABOUT": "Sur"
}

Advanced usage:

// In your app.component.ts
import { Component } from '@angular/core';
import { CfgService, DefaultCfg } from '@nwx/cfg';
import { LogService } from '@nwx/logger';
import { I18nService } from '@nwx/i18n';

@Component({
  selector: 'app-root',
  template: `<h1>{{'COMMON.WELCOME' | translate}} to {{ title }}!</h1>`
})
export class AppComponent {
  direction = 'ltr';
  title = 'Neekware';
  constructor(public cfg: CfgService, public log: LogService, public i18n: I18nService) {
    this.title = this.cfg.options.appName;

    // translate in ts files
    i18n.xlate.get('COMMON.WELCOME').subscribe((res: string) => {
      this.log.info(res);
    });

    // check if language is Right2Left `rtl`
    if (i18n.isLanguageRTL('he')) {
      this.direction = 'rtl';
    }

    // change the language
    i18n.setCurrentLanguage('fr');

    // available properties
    // direction
    // currentLanguage
    // defaultLanguage
    // enabledLanguages

    // available methods
    // isCurrentLanguage(iso)
    // getLanguageName(iso)
    // getLanguageDirection(iso)
    // isLanguageEnabled(iso)
  }
}

// In your shared.module.ts

import { I18nSharedModule } from '@nwx/i18n';

@NgModule({
  declarations: [SharedComponent],
  imports: [CommonModule, I18nSharedModule)],
})
export class SharedModule {}

// In your lazy.module.ts

import { SharedModule } from './shared';

@NgModule({
  declarations: [LazyComponent],
  imports: [CommonModule, SharedModule]
})
export class LazyModule {}

Note:

@nwx/i18n uses the great @ngx-translate package under the hood.

Running the tests

To run the tests against the current environment:

npm run ci:all

License

Released under a (MIT) license.

Version

X.Y.Z Version

`MAJOR` version -- making incompatible API changes
`MINOR` version -- adding functionality in a backwards-compatible manner
`PATCH` version -- making backwards-compatible bug fixes

Usage no npm install needed!