OneCX Multi-language Translations

Overview

In OneCX multi-language support is available via translations using @ngx-translate library.

OneCX compatible application:

  • can setup multi-language translation to support more than 1 language for the application.

Setup

To setup the multi-language translations support follow the steps listed below. Please, make sure that the application is OneCX compatible.

Step 1: Install ngx-translate Library

The @ngx-translate/core package has to be installed in the project.

npm i @ngx-translate/core

Step 2: Share ngx-translate In Webpack Configuration

The @ngx-translate/core package has to be added as a shared package in webpack configuration.

const config = withModuleFederationPlugin({
  ...
  shared: share({
    ...
    '@ngx-translate/core': { requiredVersion: 'auto' },
    ...
  }),
});

This ensures the package is shared between the app and OneCX.

Step 3: Create Translation Files

Create translation files (e.g., en.json, de.json) in a directory such as assets/i18n/. These files will contain key-value pairs for each language.

en.json
{
  "HELLO": "Hello",
  "WELCOME": "Welcome"
}

Step 4: Import Required Utilities

In your remote module file, import the following:

remote.module.ts
import { addInitializeModuleGuard, AppStateService } from '@onecx/angular-integration-interface';
import { createTranslateLoader, TRANSLATION_PATH, translationPathFactory } from '@onecx/angular-utils';

Step 5: Wrap Routes with Initialization Guard

Wrap your routes with addInitializeModuleGuard to ensure translations are loaded correctly:

remote.module.ts
imports: [
  ...
  RouterModule.forRoot(addInitializeModuleGuard(routes)),
  ...
]

Step 6: Configure TranslateModule

Add TranslateModule.forRoot() to your module’s imports array (or commonImports if shared):

remote.module.ts
imports: [
  ...
  TranslateModule.forRoot({
    isolate: false,
    loader: {
      provide: TranslateLoader,
      useFactory: createTranslateLoader,
      deps: [HttpClient]
    }
  }),
  ...
]

Step 7: Provide Translation Path

Use the TRANSLATION_PATH injection token to specify the location of your translation files:

remote.module.ts
providers: [
  ...
  {
    provide: TRANSLATION_PATH,
    useFactory: (appStateService: AppStateService) =>
      translationPathFactory('assets/i18n/')(appStateService),
    multi: true,
    deps: [AppStateService]
  },
  ...
]

⚠️ Note: Replace 'assets/i18n/' with the actual path to your translation files if different.

Step 8: Support in Feature Modules

If any feature modules use ngx-translate features (e.g., translate pipe), ensure TranslateModule is also imported in those modules:

feature.module.ts
@NgModule({
  imports: [
    ...
    TranslateModule,
    ...
  ]
})
export class FeatureModule {}

Usage

Once the setup is complete, you can use the TranslateService in your components or templates.

Templates Usage

Use translations via translate pipe.

component.html
<p>{{ 'HELLO' | translate }}</p>

TranslateService Usage

Use translations via TranslateService.

component.ts
import { TranslateService } from '@ngx-translate/core';

this.translate.get('WELCOME').subscribe((translated: string) => {
    console.log('Translated message:', translated);
});

With Parameters

Use translations with parameters. Example:

en.json
{
  "GREETING": "Hello, {{name}}! Welcome back."
}
component.html
<p>{{ 'GREETING' | translate:{ name: 'Alice' } }}</p>
component.ts
import { TranslateService } from '@ngx-translate/core';
this.translate.get('GREETING', params).subscribe((translated: string) => {
    console.log('Translated with params:', translated);
});

Language Information

The currently used language can be accessed via UserService.