ngx-translate-messageformat-compiler-ivy
    TypeScript icon, indicating that this package has built-in type declarations

    4.5.1 • Public • Published

    ngx-translate-messageformat-compiler-ivy

    Compiler for ngx-translate that uses messageformat.js to compile translations using ICU syntax for handling pluralization and gender

    Example App (StackBlitz)

    Table of Contents

    Installation

    This assumes that you've already installed ngx-translate.

    Using npm:

    npm install ngx-translate-messageformat-compiler-ivy messageformat --save

    ... or if you use yarn:

    yarn add ngx-translate-messageformat-compiler-ivy messageformat

    Something to be aware of if you deploy to strict production environments: Fundamentally, messageformat is a compiler that turns ICU MessageFormat input into JavaScript. This means it uses new Function under the hood which necessicates allowing unsafe-eval for the script-src Content Security Policy (CSP).

    Setup

    Changed dependencies for v4: You need to use Angular v6 and ngx-translate v10 for this version. Intl is expected to be present by the new messageformat version so the corresponding config option has been dropped. See CHANGELOG for more details.

    Changed dependencies for v3: You need to use Angular v4/v5 and ngx-translate v8/v9 for this version. See CHANGELOG for more details.

    Changed setup for v2: You no longer need to provide a MessageFormat instance. The compiler will do this. You still need to have messageformat installed, of course. See CHANGELOG for more details.

    Integration with ngx-translate

    You need to configure TranslateModule so it uses TranslateMessageFormatCompiler as the compiler:

    import { NgModule } from '@angular/core';
    import { BrowserModule } from '@angular/platform-browser';
    import { TranslateCompiler, TranslateModule } from '@ngx-translate/core';
    import { TranslateMessageFormatCompiler } from 'ngx-translate-messageformat-compiler-ivy';
     
    import { AppComponent } from "./app";
     
    @NgModule({
      imports: [
        BrowserModule,
        TranslateModule.forRoot({
          compiler: {
            provide: TranslateCompiler,
            useClass: TranslateMessageFormatCompiler
          }
        })
      ],
      bootstrap: [AppComponent]
    })
    export class AppModule {}

    You can override the values used when configuring MessageFormat by providing a configuration object for the MESSAGE_FORMAT_CONFIG injection token. Here's the default:

    {
      biDiSupportfalse,
      formattersundefined,
      localesundefined,
      strictNumberSignfalse
    }

    Locale initialization

    By default, messageformat initializes all locales. It is recommended that you indicate which locales you will need, like this:

    import { MESSAGE_FORMAT_CONFIG } from 'ngx-translate-messageformat-compiler-ivy';
     
    @NgModule({
      // ...
      providers: [
        { provide: MESSAGE_FORMAT_CONFIG, useValue: { locales: ['ar', 'fr'] }}
      ]
     
    })

    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: https://messageformat.github.io/messageformat/MessageFormat

    Advanced configuration

    MessageFormat instances provide some methods to influence its behaviour, among them addFormatters, setBiDiSupport, and setStrictNumberSign. Learn about their meaning here: https://messageformat.github.io/messageformat/MessageFormat

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

    import { MESSAGE_FORMAT_CONFIG } from 'ngx-translate-messageformat-compiler-ivy';
     
    @NgModule({
      // ...
      providers: [{
        provide: MESSAGE_FORMAT_CONFIG,
        useValue: {
          biDiSupport: true,
          formatters: { upcase: v => v.toUpperCase() }
        }
      }]

    Usage

    This library implements neither the syntax used for pluralization (et al) nor the "mechanics" for making translations work in your Angular app. The former is MessageFormat, the latter ngx-translate. Before you assume your problem is with ngx-translate-messageformat-compiler-ivy, please consult these ressources:

    Here's two important differences to ngx-translate's default syntax when using MessageFormat:

    • You lose the ability to access object properties in your placeholders: 'Hello {name.first} {name.last}' won't work.
    • Simple placeholders are enclosed in single curly braces instead of double curly braces: Hello {name}

    This library also exports TranslateMessageFormatDebugCompiler, which you can use as a drop-in replacement for the regular TranslateMessageFormatCompiler. The debug compiler will log to the console whenever a translation string is compiled to an interpolation function, and whenever such a function is called (with interpolation parameters) to compute the final translated string. The logs may help you figuring out which translation produces an error and the timing of when the individual steps happen.

    Here's an example to get you started:

    Example

    Translation strings:

    {
      "things": "There {count, plural, =0{is} one{is} other{are}} {count, plural, =0{} one{a} other{several}} {count, plural, =0{nothing} one{thing} other{things}}",
      "people": "{gender, select, male{He is} female{She is} other{They are}} {how}"
    }

    View template:

    <ul>
      <li translate [translateParams]="{ count: 0 }">things</li>
      <li translate [translateParams]="{ count: 1 }">things</li>
      <li>{{'things' | translate:"{ count: 2 }"}}</li>
    </ul>
    <ul>
      <li translate [translateParams]="{ gender: 'female', how: 'influential' }">people</li>
      <li translate [translateParams]="{ gender: 'male', how: 'funny' }">people</li>
      <li>{{'people' | translate:"{ how: 'affectionate' }"}}</li>
    </ul>

    Note that this illustrates using both the directives and the pipe provided by ngx-translate. You don't have to mix them, obviously.

    Output:

    - There is nothing
    - There is a thing
    - There are several things
    
    - She is influential
    - He is funny
    - They are affectionate
    

    About

    If you're here, you probably know what you're looking for. If you do wonder what this is, here's a brief explanation.

    ICU Message Format is a standardized syntax for dealing with the translation of user-visible strings into various languages that may have different requirements for the correct declension of words (e.g. according to number, gender, case) - or to simplify: pluralization.

    Messageformat.js is a compliant implementation for Javascript.

    Back in AngularJS, angular-translate, formerly by @PascalPrecht, provided support for ICU syntax using messageformat.js. This compiler "plugin" adds the same rich pluralization support to the excellent ngx-translate for Angular (2+). Thanks to @ocombe for his work and his supporting pluggable compilers in the core. Thanks also to @PascalPrecht for suggesting a contribution when I talked to him about this at Jazoon.

    Install

    npm i ngx-translate-messageformat-compiler-ivy

    DownloadsWeekly Downloads

    274

    Version

    4.5.1

    License

    MIT

    Unpacked Size

    141 kB

    Total Files

    34

    Last publish

    Collaborators

    • pontino