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');
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.
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.
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.