README

Plugin Ngx Translate

@conclurer/edel-plugin-ngx-translate implements the translation plugin defined in @conclurer/edel-core. The underlaying driver is @ngx-translate/core.

There are two ways to import NgxTranslationModule:

forChild: the most likely used import for a module. It is save to be imported, when a forRoot import is within the same or within a parent module. Multiple imports within the same module are allowed, too. Usually only the language definitions will be passed here.
forRoot: this import may only happen once in the whole application. Importing it multiple times may lead to undefined behavior. This always requires a current language selector selectCurrentLanguage for the CorePluginStore.

Best practices

All modules should have their own translations using NgxTranslationModule.forChild.
Import NgxTranslationModule.forRoot only once.
Place translations in ./localized/${lang}.json relative to your module.
Import translations as ${lang}Lang, store them in export const ${lang} = ${lang}Lang and provide them as NgxTranslationModule.forChild({ de, en }) to work around NGC restrictions.
Translations should be prefixed with their component name: MyComponent.Heading.
Translation identifiers should be written in Pascal case like MyComponent.Heading.
Translate within templates using 'MyComponent.Item'|translate.
New features should stick as near as possible to @ngx-translate/core and its plugins.

Import forChild

@conclurer/edel-plugin-ngx-translate supports module based localization definitions.

Therefore your module needs to pass these definitions to NgxTranslationModule.forChild.

// Import the translation module
import { NgxTranslationModule } from '@conclurer/edel-plugin-ngx-translate';
// Import the localizations
import * as deLang from './localized/de.json';
import * as enLang from './localized/en.json';

// You need to move these imports into variables to make the ngc happy
export const de = deLang;
export const en = enLang;

@NgModule({
  imports: [
    // Import the translations
    NgxTranslationModule.forChild({
      definitions: { de, en }
    })
  ]
})
export class MyModule {}

Where your translation files look like:

{
  "MyComponent": {
    "Heading": "Translations are great"
  }
}

forChild module config

definitions: Contains the localization definitions. They need to map the languages to their translations, like { de: { Greeting: 'Hallo' }, en: { Greeting: 'Hello' }}.
ngxConfig: A config for @ngx-translate/core.

Import forRoot

In contrast to the forChild import, forRoot

may only imported once
requires selectCurrentLanguage in order to watch for language changes
watching for language changes may leak memory when imported multiple times

// Import the translation module
import { NgxTranslationModule } from '@conclurer/edel-plugin-ngx-translate';

// declare current language selector
export function selectCurrentLanguage(from: CoreRootState): string | null {
  return 'en';
}

@NgModule({
  imports: [
    // Import the root config
    NgxTranslationModule.forRoot({
      selectCurrentLanguage
    })
  ]
})
export class AppModule {}

forRoot module config

selectCurrentLanguage: Resolves the current language whenever the core root state changes. (from: CoreRootState): string | null => 'en'.
definitions: Contains the localization definitions. They need to map the languages to their translations, like { de: { Greeting: 'Hallo' }, en: { Greeting: 'Hello' }}.
ngxConfig: A config for @ngx-translate/core.

JSON Imports

In order to import *.json files, ensure you can import these, add the following declaration to your project. The NGC will replace these imports by null when providing these directly. As a workaround you need to temporarily store those within an export const.

// src/typings.d.ts
declare module '*.json' {
  const value: any;
  export default value;
}

Contributing

# install dependencies
$ yarn

# Before commit
$ yarn format

# Publish new version
$ yarn build && npm publish dist

Usage no npm install needed!