@odx/angular-translate

Install 🚀

npm install @odx/angular-translate

Library structure

• @odx/angular-translate: main entry point
  • provideTranslate: Main provider factory to enable translations for an Angular application
  • TranslateModule: Angular module which bundles all directives and pipes for the UI
  • TranslateService: Service to perform different tasks regarding translation
  • ...

Usage

Import the TranslateModule from @odx/angular-translate and add it to the application imports, to configure it use the provideTranslate function.

provideTranslate({
  domains: ['SPA_COMMON', 'SPA_USER'],
  environment: TranslateApiEnvironment.DEV,
}),

The configuration object has the following interface:

interface TranslateConfig {
  domains: string | string[];
  environment: TranslateApiEnvironment;
  prodMode?: boolean;
  localTranslationUrl?: string;
  missingKeyHandler?: MissingKeyHandlerFn;
  internal?: TranslateInternalConfig;
  showDebugInformation?: boolean;
}

Use the LocalizationService.setLanguage method from @odx/angular/localization to change the language.

Simple example with local translations

Provide translations in application providerts:

@NgModule({
  ...
  providers: [
    ...
    provideHttpClient(),
    provideLocalization({ availableLanguages: ['en', 'de'] }),
    provideTranslate(
      { environment: TranslateApiEnvironment.LOCAL },
        withPreloadTranslations(['en', 'de'])
    ),
    ...
  ]
  ...
})

Locally, in 'assets/locales' save 2 files: en.json:

{ "text": "Translation example" }

and de.json:

{ "text": "Beispiel für eine Übersetzung" }

in your component imports add TranslatePipe.

  @Component({
    ...
    imports: [TranslatePipe],
    ...
  })
  export class YourComponent {
    ...
  }

<p>{{ 'text' | odxTranslate }}</p>

or TranslateDirective to use with directive:

  @Component({
    ...
    imports: [TranslateDirective],
    ...
  })
  export class YourComponent {
    ...
  }

<ng-container *odxTranslate="let t">
  <p>{{ t('text') }}</p>
</ng-container>

Changing the language:

  @Component({
    ...
  })
  export class YourComponent {
    private readonly localizationService = inject(LocalizationService);
    ...

    public setGermanLanguage(): void {
      this.localizationService.setActiveLanguage('de')
    }
  }

Unit testing

When running specs, we want to have the languages available immediately, in a synchronous fashion. @odx/angular-translate provides you with a provideTranslateMock function, where you can mock a translation and set a default language. By default the mock uses an empty translation and the language code en.

import { provideTranslateMock } from '@odx/angular-translate/testing';

// ...
[
  providers: [provideTranslateMock(/** options */)],
]

// ...
const element = fixture.debugElement.query(By.css('h1')).nativeElement;
expect(element).toHaveText('en.my.translationKey');

Unit testing with Jest

The @odx/angular-translate libraries uses @jsverse/transloco internally, therefore when using jest for unit testing, you need to add the following to your jest.preset.js:

moduleNameMapper: {
  '^flat': 'node_modules/flat/index.js',
},

The dependency flat is published as ESM.