Migrating to v5 (Angular)

In version 5, the core library was completely redesigned. Before you start, please read the general info about this new version.

Initialization

In v4 the initialization of Tolgee for angular was done by passing configuration parameters to forRoot method. You will need to provide a Tolgee instance using TOLGEE_ISTANCE injection token.

app.module.ts

...
import {
  Tolgee,
  TOLGEE_INSTANCE,
} from '@tolgee/ngx';

@NgModule({
  ...
  providers: [
    {
      provide: TOLGEE_INSTANCE,
      useFactory: () => {
        return Tolgee() // << The initialization of Tolgee instance is here
          .use(...)
          .use(...)
          .init({
            apiUrl: environment.tolgeeApiUrl,
            apiKey: environment.tolgeeApiKey,
            fallbackLanguage: 'en',
            defaultLanguage: 'en',
            ...
          });
      },
    },
  ],
  ...
})
export class AppModule {}

The initialization & configuration of Tolgee is described here.

The Formatter

In v4, the ICU formatter was bundled with @tolgee/core, and used as the only formatting option. If you are already using ICU features in your strings, you can add ICU message format support by installing @tolgee/format-icu and providing it to Tolgee instance via use() method.

app.module.ts

import { FormatIcu } from '@tolgee/format-icu';
...

// Add this to the useFactory function
return Tolgee()
  .use(FormatIcu())
  ...

If you only need parameter interpolation and you don't need to format advanced plurals, selects, dates, or use other cool ICU features, you can stick with FormatSimple plugin, which is more lightweight. The FormatSimple module is included in @tolgee/core, so you don't have to install it.

app.module.ts

import { FormatSimple } from '@tolgee/core';

// Add this to the useFactory function
return Tolgee()
  .use(FormatSimple())

Providing the localization data

If you were not using the staticData configuration property for providing the localization data in production, the localization data were fetched automatically from the static assets of your app. To continue using this approach, you need to use BackendFetch plugin.

Suppose you are using the staticData property. You can continue using it the same way.

app.module.ts

import { FormatSimple } from '@tolgee/core';

// Add this to the useFactory function
return Tolgee()
  .use(BackendFetch())

Usage

While the T component API is still the same, the API of the translate pipe and TranslateService APIs are changed. The stranslate pipe was removed and replaced with a parameter of translate pipe.

The translate pipe

The translate pipe API now shares the same API as tolgee.t. In most cases the usage is the same, but it allows new ways of usage.

For example, you can provide all the parameters via the options object.

<div>{{ { key: 'this_is_a_key', defaultValue: 'Jeeey!' } | translate}}</div>

The stranslate pipe

The stranslate pipe was removed, but you can achieve the same result using noWrap parameter.

{ 'this_is_a_key' | translate:{ noWrap: true } }}

The TranslateService methods.

In the TranslateService, there is no get or getSafe method anymore. Instead, there is translate and instant method.

The translate method accepts the same arguments as tolgee.t and returns Observable, emitting on every value change.

The instant method is similar, but returns a string value.

To switch language, you can use the changeLanguage method and languageAsync property.

<select
  [value]="translateService.languageAsync | async"
  (change)="translateService.changeLanguage($event.target.value)"
  class="lang-selector">
  <option value="en">🇬🇧 English</option>
  <option value="de">🇩🇪 Deutsch</option>
</select>

To read more about Angular integration, read the Angular integration docs.