Message Format

The @jsverse/transloco-messageformat package integrates Transloco with @messageformat/core, enabling the compilation of translations using ICU syntax. This allows for advanced handling of pluralization and gender in your app's translations.

MessageFormat provides a robust mechanism for handling linguistic rules, making your app's translations more dynamic and user-friendly. For a detailed guide on its syntax, refer to MessageFormat's format guide.

---

Installation

pnpm

pnpm add @jsverse/transloco-messageformat

yarn

yarn add @jsverse/transloco-messageformat

npm

npm install @jsverse/transloco-messageformat

Usage

The MessageFormatTranspiler is fully compatible with Transloco's default transpiler, so you can safely switch without impacting your existing translations. With this plugin, you can use ICU syntax in your translation files:

en.json

{
  "mySelectRule": "{myVar, select, val1 {Value 1} val2 {Value 2} other {Other Value}}",
  "myPluralRule": "{myCount, plural, =0 {no results} one {1 result} other {# results}}"
}

Standalone

To enable the plugin, include the following provider in your app providers:

import { provideTranslocoMessageformat } from '@jsverse/transloco-messageformat';

bootstrapApplication(AppComponent, {
  providers: [
    provideTranslocoMessageformat(),
  ],
});

NgModule

To enable the plugin, include the following provider in your TranslocoRootModule:

transloco-root.module.ts

import { provideTranslocoMessageformat } from '@jsverse/transloco-messageformat';

@NgModule({
  providers: [
    provideTranslocoMessageformat(),
  ],
  ...
})
export class TranslocoRootModule {}

Locale Initialization

By default, MessageFormat initializes all locales. You can customize this by specifying the locales you need:

Standalone

bootstrapApplication(AppComponent, {
  providers: [
    provideTranslocoMessageformat({
      locales: 'en-GB', // or ['en-GB', 'fr']
    }),
  ],
});

NgModule

transloco-root.module.ts

@NgModule({
  providers: [
    provideTranslocoMessageformat({
      locales: 'en-GB', // or ['en-GB', 'fr']
    }),
  ],
  ...
})
export class TranslocoRootModule {}

locales: Accepts a string or an array of strings. The first locale is used as the default by MessageFormat. For more details, refer to MessageFormat locales.

---

Advanced Configuration

MessageFormat provides additional options, such as:

• customFormatters: Add custom formatting functions.

• biDiSupport: Enable bidirectional support for right-to-left languages.

• strictNumberSign: Strictly interpret # in plural rules.

Example configuration with advanced options:

Standalone

bootstrapApplication(AppComponent, {
  providers: [
    provideTranslocoMessageformat({
      biDiSupport: true,
      customFormatters: {
        upcase: (v: string) => v.toUpperCase(),
      },
    }),
  ],
});

NgModule

transloco-root.module.ts

@NgModule({
  providers: [
    provideTranslocoMessageformat({
      biDiSupport: true,
      customFormatters: {
        upcase: (v: string) => v.toUpperCase(),
      },
    }),
  ],
  ...
})
export class TranslocoRootModule {}

Caching v3+

From version 3 onward, the compiled output of MessageFormat is cached by default to improve performance. If you wish to disable caching, you can set the enableCache option to false:

Standalone

bootstrapApplication(AppComponent, {
  providers: [
    provideTranslocoMessageformat({
      enableCache: false,
    }),
  ],
});

NgModule

transloco-root.module.ts

@NgModule({
  providers: [
    provideTranslocoMessageformat({
      enableCache: false,
    }),
  ],
  ...
})
export class TranslocoRootModule {}

---

This integration empowers you to use ICU syntax for advanced pluralization, gender, and linguistic rules, making your translations more accurate and expressive.