@qntm-code/ng-lazy-translate

Lazy loaded translation module for Angular using messageformat.

Installation

npm i @qntm-code/ng-lazy-translate

Usage - Standalone Components

1. Create providers

import { bootstrapApplication } from '@angular/platform-browser';
import { appConfig } from './app/app.config';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, appConfig).catch(err => console.error(err));

import { provideHttpClient } from '@angular/common/http';
import { ApplicationConfig } from '@angular/core';
import { provideLazyTranslate } from '@qntm-code/ng-lazy-translate';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideLazyTranslate({
      defaultLanguage: 'en',
      languages: [
        {
          code: 'en',
          displayValue: 'English',
        },
        {
          code: 'fr',
          displayValue: 'Français',
        },
      ],
      translationAssetPaths: {
        'en.common': 'asset/i18n/en/common.json',
        'fr.common': 'asset/i18n/fr/common.json',
      },
      missingTranslationHandler: (language: string, key: string) => console.error(`Custom handler: Could not find ${key} in ${language}`),
      missingFileHandler: (namespace: string, language: string) =>
        console.error(`Custom handler: CFile with namespace ${namespace} not found for language ${language}`),
    }),
  ],
};

Usage - Within a Module

1. Import Module

import { NgModule } from '@angular/core';
import { HttpClientModule } from '@angular/common/http';
import { NgLazyTranslateModule } from '@qntm-code/ng-lazy-translate';

@NgModule({
  imports: [
    HttpClientModule,
    NgLazyTranslateModule.forRoot({
      defaultLanguage: 'en',
      languages: [
        {
          code: 'en',
          displayValue: 'English',
        },
        {
          code: 'fr',
          displayValue: 'Français',
        },
      ],
      translationAssetPaths: {
        'en.common': 'asset/i18n/en/common.json',
        'fr.common': 'asset/i18n/fr/common.json',
      },
    }),
  ],
})
export class AppModule {}

2. Import module in component

import { Component } from '@angular/core';
import { NgLazyTranslateModule } from '@qntm-code/ng-lazy-translate';

@Component({
  standalone: true,
  imports: [NgLazyTranslateModule],
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss'],
})
export class AppComponent {}

Using pipe in a template

<p>{{ 'common.hello_world' | translate }}</p>

Using the service in a component/service

import { Injectable } from '@angular/core';
import { LazyTranslateService } from '@qntm-code/ng-lazy-translate';

@Injectable()
export class MyService {
  constructor(private readonly translateService: LazyTranslateService) {}

  public doSomething(): Observable<string> {
    return this.translateService.translate('common.hello_world');
  }
}

LazyTranslateModuleConfig

Whether you use the standalone components or the module, the LazyTranslateModuleConfig options are the same.

| Option | Type | Description | Mandatory | Default | | ------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------- | | defaultLanguage | string | The default language to use if no language is specified | Yes | N/A | | languages | Language[] | The list of languages to support | Yes | N/A | | translationAssetPaths | TranslationAssetPaths | The list of translation assets to load. The key is the language and the translation file name. | Yes | N/A | | useDefaultLanguage | boolean | Whether to use the default language if the specified language is not found | No | true | | enableLogging | boolean | Whether to enable logging of missing translations | No | true | | missingTranslationHandler | (language: string, key: string) => void | A custom handler to use when a translation is not found. If not specified, the default handler will be used. | No | Will console.error a message | | missingFileHandler | (namespace: string, language: string) => void | A custom handler to use when a translation file is not found. If not specified, the default handler will be used. | No | Will console.error a message |

Language

| Option | Type | Description | | ----------- | ------ | ------------------ | | code | string | The language code. | | displayName | string | The language name. |

TranslationAssetPaths

| Option | Type | Description | | ------ | ------ | ---------------------------------------------------------------------------- | | key | string | The language and translation file name. For example: en.common or fr.app | | value | string | The path to the translation file. e.g assets/i18n/en.common.json |

Translation files

Translation files must be in JSON format and have the following structure:

{
  "hello_world": "Hello World!"
}

You can also use nested keys:

{
  "greetings": {
    "hello_world": "Hello World!"
  }
}

You can then access this nest value like so:

• In a template:

  {{ 'common.greetings.hello_world' | translate }}

• In a component/service:

  this.translateService.translate('common.greetings.hello_world');

The translation service uses messageformat to format the translation., which allows you to pass values to your translated text:

{
  "greetings": {
    "hello_world": "Hello {name}! It is {time}"
  }
}

• Template:

  {{ 'common.greetings.hello_world' | translate: { name: 'John', time: '10:00' } }}

• Component/Service:

  this.translateService.translate('common.greetings.hello_world', { name: 'John', time: '10:00' });

Default value

If you want to provide a default value for when a translation is not found in any language, you can do so by passing it as the last parameter to the translate pipe or function:

• Template:

  {{ 'common.greetings.hello_world' | translate: { name: 'John', time: '10:00' }: 'Hello, this is my default string' }}

  or without values:

  {{ 'common.greetings.hello_world' | translate: 'Hello, this is my default string' }}

• Component/Service:

  this.translateService.translate('common.greetings.hello_world', { name: 'John', time: '10:00' }, 'Hello, this is my default string');

  or without values:

  this.translateService.translate('common.greetings.hello_world', undefined, 'Hello, this is my default string');