Translating with Angular

To get full image of working Angular integration check our Angular example application.

To translate strings in Angular you can use pipe or translation methods.

Using pipe

To translate a string use translate pipe.

<h1>{{'hello_world' | translate}}</h1>

To provide parameters for translation pass them as first parameter of translate pipe.

params = { name: 'John Doe' };

<h1>{{'hello' | translate:params}}</h1>

You can also provide default value.

<h1>{{'hello' | translate:params:'Default!'}}</h1>
// with params
<h1>{{'hello' | translate:'Default!'}}</h1>
// or without params

Element with t attribute

You can also use element with t attribute. Angular will render Tolgee component with t attribute selector.

<h1 t key="providing_default_values"></h1>
<p t key="Peter has n dogs" [params]="params"></p>
// with params

Default value can be provided as well

<p t key="using_t_with_default" default="This is default"></p>

Using translate methods

To translate texts in your component code use get or instant method.

These methods are part of translateService, which can be injected by dependency injection:

import { Component, OnInit } from '@angular/core';
import { TranslateService } from '@tolgee/ngx';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent implements OnInit {
  constructor(private translateService: TranslateService) {}

  helloWorld: string;

  async ngOnInit(): Promise<void> {
    this.translateService
      .get('hello_world')
      .subscribe((r) => (this.helloWorld = r));
  }
}

get method returns Observable as the result. That means, the result is provided asynchronously, when the localization strings are loaded.

this.translateService
  .get('hello_world')
  .subscribe((r) => (this.helloWorld = r));

If you are unable to use this asynchronous approach for some reason, you can use instant method.

this.helloWorld = this.translateService.instant('hello_world');

danger

Don't overuse instant method. When it's possible always use get method. When the translations are not loaded, instant method will not provide a valid result. Unfortunately this can happen just in production mode, so this could lead to very confusing bugs.

Parameter interpolation

If you would like to provide parameters for interpolation, pass your params object as second parameter to get or instant functions.

this.translateService
  .get('hello', { name: 'John Doe' })
  .subscribe((r) => (this.hello = r));

Safe translating (without wrapping)

When translating with Tolgee, there could be situations, when your texts are rendered incorrectly because of wrapping. For example encoded strings like %-%tolgee:something%-% will be rendered in your document or tooltips will be rendered with incorrect width. To handle this, you can disable wrapping and let Tolgee to translate texts right away.

To avoid wrapping of localization string in development mode use stranslate pipe, getSafe or instantSafe methods.

Doing this will disable in-context localization for this string.

Changing language

To change language, use setLang method of translateService.

this.translateService.setLang('en');

Obtaining current language

To obtain current language, use getCurrentLang method of translateService.

this.translateService.getCurrentLang();

Subscribing to language change event

Your imperatively translated texts will be not automatically updated in production mode. To do so, you will need to listen to onLanguageChange EventEmitter and refresh your values manually.

  async ngOnInit(): Promise<void> {
    this.refresh()
    this.translateService.onLangChange.subscribe(() => this.refresh());
  }

  private refresh() {
    this.translateService.get('hello').subscribe(r => this.hello = r);
  }

Translations with HTML tags

Our JS SDKs currently don't support rendering of HTML tags natively. However, if you really really need to render HTML tags there is a way.

danger

This is dangerous, and you should know what you are doing.

Consider a translation value:

'<h1>'Hello'</h1>'

Notice that h1 tags are wrapped with ' characters. This tells ICU message formatter to ignore those tags. To get HTML you can use TranslateService.getSafe method.

this.translateService.getSafe('key_with_html_translation', undefined).subscribe(
  (r) => (this.translated = r) // r is <h1>Hello</h1>
);

Nice, but Angular doesn't allow us to set HTML into element so easily, so we have to set it using [innerHtml] attribute, which enables us to set inner HTML of the element.

<div
  data-tolgee-key-only="key_with_html_translation"
  [innerHtml]="translated"
></div>

Using data-tolgee-key-only we tell Tolgee, that there is a key in the element. So it will enable its in-context localization.

danger

Using of [innerHtml] attribute is not safe, since somebody can simply inject an HTML into a parameter. When you are doing this you have to be sure, that your translation or params don't contain any dangerous HTML code.

TIP: Maybe you can remove tags from your translated value or parameters using striptags library.

Message format

All Tolgee integrations follow ICU message format standard.

{dogsCount, plural, one {One dog is} other {# dogs are}} here.

To read more about it, check ICU Message Format documentation page.

All Tolgee JS integrations are using MessageFormat class of formatJs library.