@larscom/ngx-translate-module-loader

Highly configurable and flexible translations loader for @ngx-translate/core. Fetch multiple translations (http only) and configure them to your needs. Each translation file has it's own namespace out of the box so the key/value pairs do not conflict with each other.

✨ View on StackBlitz

Dependencies

@larscom/ngx-translate-module-loader depends on @ngx-translate/core and Angular.

Installation

1npm install @larscom/ngx-translate-module-loader

Choose the version corresponding to your Angular version

@angular/core	@larscom/ngx-translate-module-loader
>= 12	>= 3.0.0
< 12	<= 2.2.0

Usage

Create an exported moduleHttpLoaderFactory function

1import { NgModule } from '@angular/core'
2import { BrowserModule } from '@angular/platform-browser'
3import { HttpClientModule, HttpClient } from '@angular/common/http'
4import { TranslateModule, TranslateLoader } from '@ngx-translate/core'
5import { ModuleTranslateLoader, IModuleTranslationOptions } from '@larscom/ngx-translate-module-loader'
6import { AppComponent } from './app'
7
8export function moduleHttpLoaderFactory(http: HttpClient) {
9  const baseTranslateUrl = './assets/i18n'
10
11  const options: IModuleTranslationOptions = {
12    modules: [
13      // final url: ./assets/i18n/en.json
14      { baseTranslateUrl },
15      // final url: ./assets/i18n/feature1/en.json
16      { baseTranslateUrl, moduleName: 'feature1' },
17      // final url: ./assets/i18n/feature2/en.json
18      { baseTranslateUrl, moduleName: 'feature2' }
19    ]
20  }
21
22  return new ModuleTranslateLoader(http, options)
23}
24
25@NgModule({
26  imports: [
27    BrowserModule,
28    HttpClientModule,
29    TranslateModule.forRoot({
30      loader: {
31        provide: TranslateLoader,
32        useFactory: moduleHttpLoaderFactory,
33        deps: [HttpClient]
34      }
35    })
36  ],
37  bootstrap: [AppComponent]
38})
39export class AppModule {
40  constructor(readonly translate: TranslateService) {
41    translate.setDefaultLang('en')
42  }
43}

Namespacing

By default, each translation file gets it's own namespace based on the moduleName, what does it mean?

For example with these options:

1export function moduleHttpLoaderFactory(http: HttpClient) {
2  const baseTranslateUrl = './assets/i18n'
3
4  const options: IModuleTranslationOptions = {
5    modules: [
6      // no moduleName/namespace
7      { baseTranslateUrl },
8      // namespace: FEATURE1
9      { baseTranslateUrl, moduleName: 'feature1' },
10      // namespace: FEATURE2
11      { baseTranslateUrl, moduleName: 'feature2' }
12    ]
13  }
14  return new ModuleTranslateLoader(http, options)
15}

Lets say each module in the above example resolves to the following JSON:

1{
2  "KEY": "VALUE"
3}

The final translation you are working with would be:

1{
2  "KEY": "VALUE",
3  "FEATURE1": {
4    "KEY": "VALUE"
5  },
6  "FEATURE2": {
7    "KEY": "VALUE"
8  }
9}

Even though all JSON files from those modules are the same, they don't conflict because they are not on the same level after they get merged.

Configuration

The configuration is very flexible, you can even define custom templates for fetching translations.

1interface IModuleTranslationOptions {
2  /**
3   * The translation module configurations
4   */
5  modules: IModuleTranslation[]
6  /**
7   * By default, each module gets its own namespace so it doesn't conflict with other modules
8   */
9  disableNamespace?: boolean
10  /**
11   * By default, namespaces are uppercase
12   */
13  lowercaseNamespace?: boolean
14  /**
15   * By default, it'll perform a deepmerge when merging translation files
16   */
17  deepMerge?: boolean
18  /**
19   * Set a version to prevent the browser from caching the translation files.
20   * Each translation will get a query parameter with the version number
21   * @example 'en.json?v=123'
22   */
23  version?: string | number
24  /**
25   * Function that gets executed if an error occurred while retrieving a translation file
26   * @param error the error that occurred
27   * @param path the path to the location file
28   */
29  translateError?: (error: any, path: string) => void
30  /**
31   * Custom translate merge function after retrieving all translation files
32   * @param translations the resolved translation files
33   */
34  translateMerger?: (translations: Translation[]) => Translation
35  /**
36   * Provide custom headers at 'root' level, which means this headers gets added to every request
37   * unless you specify headers at 'module' level.
38   * @see modules
39   */
40  headers?: HttpHeaders
41}

1interface IModuleTranslation {
2  /**
3   * The module name
4   *
5   * For example: shared
6   * @description omit moduleName if you have a translate file at baseTranslateUrl level
7   * @see baseTranslateUrl
8   */
9  moduleName?: string
10  /**
11   * The base translate URL
12   *
13   * For example: ./assets/i18n
14   * @description the final url will then be: ./assets/i18n/shared if the moduleName is shared
15   * @see moduleName
16   */
17  baseTranslateUrl: string
18  /**
19   * By default, it uses the moduleName as namespace
20   * @see moduleName
21   *
22   * Use this property if you want to override the default namespace
23   */
24  namespace?: string
25  /**
26   * Custom translation map function after retrieving a translation file
27   * @param translation the resolved translation file
28   */
29  translateMap?: (translation: Translation) => Translation
30  /**
31   * Custom path template for fetching translations
32   * @example
33   * '{baseTranslateUrl}/{moduleName}/{language}'
34   * or
35   * @example
36   * '{baseTranslateUrl}/{language}'
37   *
38   * It depends whether you have a moduleName defined
39   * @see moduleName
40   */
41  pathTemplate?: string
42  /**
43   * Provide custom headers at 'module' level. These headers only apply to this module.
44   */
45  headers?: HttpHeaders
46}

Custom templates for fetching translations

By default, translations gets fetched by using the following template:

'{baseTranslateUrl}/{moduleName}/{language}' e.g. ./assets/feature1/en.json

You can override this option if you wish to do so:

1const options: IModuleTranslationOptions = {
2  modules: [
3    // resolves to: ./assets/my-path/en.json
4    { baseTranslateUrl, pathTemplate: '{baseTranslateUrl}/my-path/{language}' },
5    // resolves to: ./assets/my-path/en/feature1.json
6    { baseTranslateUrl, moduleName: 'feature1', pathTemplate: '{baseTranslateUrl}/my-path/{language}/{moduleName}' },
7    // resolves to: ./assets/my-path/en/feature2.json
8    { baseTranslateUrl, moduleName: 'feature2', pathTemplate: '{baseTranslateUrl}/my-path/{language}/{moduleName}' }
9  ]
10}

Custom headers

1  const options: IModuleTranslationOptions = {
2    // global headers, applied to every request, unless you specify headers at 'module' level
3    headers: new HttpHeaders().set('Header-Name', 'Header value')
4    modules: [
5      { baseTranslateUrl },
6      // headers only applied to this module
7      { baseTranslateUrl, moduleName: 'feature1', headers: new HttpHeaders().set('Header-Name', 'Header value') },
8      { baseTranslateUrl, moduleName: 'feature2' }
9    ]
10  };