Angular Fluent

An Angular package for translations using Fluent.

Usage

One locale

Put the translation files into the assets folder:

/assets/i18n/<locale>.ftl

Import the library in the app modules:

import { AngularFluentModule } from "angular-fluent";

@NgModule({
  imports: [
    BrowserModule,
    AngularFluentModule,
    HttpClientModule,
  ],
  providers: [
    AngularFluentService,
  ],
})

In the app component import the main service and set the locale. For example to initialize the service with German use:

import { Component } from '@angular/core';
import { AngularFluentService } from 'angular-fluent';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
})
export class AppComponent {
    constructor(private angularFluentService: AngularFluentService) {}

    ngOnInit() {
        this.angularFluentService.setLocale('de');
    }
}

Pipe

You can now use the pipe anywhere in your project to translate strings:

{{ 'number-messages' | fluent:{number: 3} }}

To force a locale different from the one set in the service use:

{{ 'number-messages' | fluent:{number: 3, locale: 'hu'} }}

Translation-Service

export class AppComponent {
  async awaitTranslation(key: string) {
    const translation = await this.angularFluentService.translate(key);
    console.log(translation);
  }
}

Language switching

Switching languges is as simple as calling the setLocale() function and passing the new locale.

export class AppComponent {
    switchLocale(locale: string) {
        this.angularFluentService.setLocale(locale);
    }
}

Fallbacks and hybrid localization

Angular Fluent can store an array of fallback locales in the service, which are used if a message can't be resolved in the primary locale. The fallback locales are prioritized / used in the order of the given array.

This is particularly interesting if the locale priority is taken from the user's browser locale settings. Because each message is resolved individually that means a page can use hybrid localization, where if not all locales are translated completely the messages are resolved individually to provide the best translation according to a user's language competences.

Fallback locales can be set like this and are then used automatically by the translation pipe:

export class AppComponent {
    setFallbackLocales() {
        const fallbacks: string[] = ['hu', 'es', 'pl'];
        this.angularFluentService.setFallbackLocales(fallbacks);
    }
}

Return message key for unresolved messages

In some cases returning null for unresolved messages might be undesirable. It is possible to return the message key instead:

export class AppComponent {
    ngOnInit() {
        this.angularFluentService.setReturnKeyForUnresolvedMessages(true);
        this.angularFluentService.setLocale('de');
    }
}

Installation

Install the following 2 packages:

npm i @fluent/bundle --save
npm i angular-fluent --save

Development

Build

Run ng build angular-fluent to build the project. The build artifacts will be stored in the dist/ directory.

Publishing

After building your library with ng build angular-fluent, go to the dist folder cd dist/angular-fluent and run npm publish.

Running unit tests

Run ng test angular-fluent to execute the unit tests via Karma.