Skip to main content

Message Format

Transpiler for @jsverse/transloco that uses @messageformat/core to compile translations using ICU syntax for handling pluralization and gender.

Messageformat is a mechanism for handling both pluralization and gender in your app.

You can see its format guide here.

Installation​

npm i @jsverse/transloco-messageformat

Usage​

The MessageFormatTranspiler is compatible with the DefaultTranspiler and therefore you can switch without worry that it will break your current translations.

It then enables support for the following within your i18n 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}}"
}

To enable this plugin, add the following import 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 could also provide the locales you will need:

transloco-root.module.ts
@NgModule({
  providers: [
    provideTranslocoMessageformat({
        locales: 'en-GB'
    })
  ],
  ...
})
export class TranslocoRootModule {}

The value for locales is either a string or an array of strings. The first locale is used as the default locale by messageformat. More info here.

Advanced configuration​

MessageFormat instances provides some options to influence its behaviour, among them customFormatters, biDiSupport, and strictNumberSign. Learn about their meaning here

This is how you would enable bidirectional support and add a custom formatter, for example:

transloco-root.module.ts
 @NgModule({
   imports: [
     TranslocoMessageFormatModule.forRoot({
         biDiSupport: true,
         customFormatters: { upcase: v => v.toUpperCase() }
     })
   ],
   ...
 })
 export class TranslocoRootModule {}

Caching (from v3)​

By default, the messageformat compile output is cached to reduce computing times, you can disable caching by passing the enableCache option:

transloco-root.module.ts
@NgModule({
  imports: [
    TranslocoMessageFormatModule({
        enableCache: false,
    })
  ],
  ...
})
export class TranslocoRootModule {}