Translate

This library was created to work well with signals in angular 17.3.0 and above.

Installation

Install the package

npm install --save-exact @wolve/translate

Add it to your angular project:

export const appConfig: ApplicationConfig = {
  providers: [
    
    // ...

    // This will add all the required services to your module.
    // It is recommended that you provide them in your root module.
    provideTranslations({
      defaultLanguage: 'en',
      supportedLanguages: ['en', 'de', 'fr', 'es', 'it'],
      filePrefix: '.json',
      urlToI18n: 'assets/i18n'
    }),

    // ...
  ]
};

with this config you the module will expect translation files in the folder 'src/assets/i18n' (or in release build 'assets/i18n') for each language a separate file structured as json is expected.

Usage

get a translated value

The recommended usage is to translate using the translate service. Therefore there are 3 methods available:

1. get

returns a signal to a translation. If the language changes signal will be notified and updated

import { TranslateService } from '@wolve/translate';
import { inject, Signal } from '@angular/core';

// ...

private readonly translateService = inject(TranslateService);

// this requires a format like '{"path": {"to": {"translation": {"key": "your translation!"}}}}' in the translation json
public readonly translation: Signal<string> = this.translateService.get('path.to.translation.key');

// ...

2. instant

Returns the translated key once in real time. If the selected language changes the value will NOT change

import { TranslateService } from '@wolve/translate';
import { inject } from '@angular/core';

// ...

private readonly translateService = inject(TranslateService);

public readonly translation: string = this.translateService.instant('path.to.translation.key');

// ...

3. stream

creates an observable to the translated value. If the language changes the observable will be notified

import { TranslateService } from '@wolve/translate';
import { inject } from '@angular/core';
import { interval } from 'rxjs';

// ...

private readonly translateService = inject(TranslateService);

public readonly translation: Observable<string | null> = this.translateService.stream('path.to.translation.key');

// ...

select the language

only languages that are provided as supported or default languages in the initialization of the module can be selected.

import { TranslateService } from '@wolve/translate';

// ...

private readonly translateService = inject(TranslateService);

// ...

// all the language will be loaded if it has never been selected before and signals/observables will be notified
this.translateService.selectLanguage('fr');

translate pipe

@Component({
  standalone: true,
  selector: 'app-translate-pipe-demo',
  templateUrl: './translate-pipe-demo.component.html',
  styleUrls: ['./translate-pipe-demo.component.scss'],
  imports: [
    TranslatePipe,
  ],
})
export class TranslatePipeDemoComponent {}

template:

<p> {{ 'path.to.translate.key' | translate }} </p>

with parameters.

<p> {{ 'path.to.translate.key' | translate: {param1:'Some custom value'} }} </p>

translate directive

@Component({
  standalone: true,
  selector: 'app-translate-pipe-demo',
  templateUrl: './translate-pipe-demo.component.html',
  styleUrls: ['./translate-pipe-demo.component.scss'],
  imports: [
    TranslatePipe,
  ],
})
export class TranslatePipeDemoComponent {}

the template:

<p translate>path.to.translate.key</p>

OR

<p translate="path.to.translate.key"></p>

with parameters

<p translate [translateParams]="{param1: 'ParamValue'}">path.to.translate.key</p>

OR

<p translate="path.to.translate.key" [translateParams]="{param1: 'ParamValue'}"></p>

translation parameters

parameters are passed as Record<string, string> to the methods

tranlsation json format

consider you have a path like 'path.to.your.translations'

this will expect a json file like

{
    "path": {
        "to": {
            "your": {
                "translation": "Thats the actual translation"
            }
        }
    }
}

for non static translations you can provide custom parameters like:

{
    "translation": {
        "withParams": "There are {{numberOfEntries}} entries missing"
    }
}

calling translateService.instant('translation.withParams', {numberOfEntries: '2'}); will translate to 'There are 2 entries missing'