Translation API

Below is a list of the TranslocoService API and their usages:

translate()

Translate the given key. Sometimes you may need to translate a key in a component or a service. To do so, you can inject the TranslocoService and use its translate method:

app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService) {}
ngOnInit() {
this.translocoService.translate('hello');
this.translocoService.translate('hello', { value: 'world' });
this.translocoService.translate(['hello', 'key']);
this.translocoService.translate('hello', params, 'es');
// Translate a key from a specific scope
this.translocoService.translate('hello', params, 'todos/en');
}
}
important

Note that in order to safely use this method, you are responsible for ensuring that the translation files have been successfully loaded by the time it's called.

If you aren't sure, you can use the selectTranslate() method instead:

selectTranslate()

Returns an observable that when subscribed load the translation file and emits the translation of the given key:

app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService) {}
ngOnInit() {
// Don't forget to unsubscribe
this.translocoService.selectTranslate('hello')
.subscribe(value => ...);
this.translocoService.selectTranslate('hello', params})
.subscribe(value => ...);
this.translocoService.selectTranslate('hello', params, lang)
.subscribe(value => ...);
}
}

selectTranslate will emit each time the active language is changed.

You can also select a translation from scope, simply inject the scope using the TRANSLOCO_SCOPE token and provide it to the selectTranslate function:

app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService,
@Inject(TRANSLOCO_SCOPE) private scope
) {}
ngOnInit() {
this.translocoService.selectTranslate('title', params, this.scope)
.subscribe(console.log);
}
}

translateObject()

en.json
{
"home": "Home",
"hello": "Hello {{ name }}",
"some": {
"object": {
"hi": "Hi",
"hey": "Hey"
}
},
"path": {
"to": {
"object": {
"welcome": "Welcome {{ name }}",
"nested": {
"subscribe": "subscribe today for {{ price }}$"
}
}
}
}
}

The following code is based on the en.json above ☝

  • Returns an object based on the given path:
app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService) {}
ngOnInit() {
let result = this.translocoService.translateObject('some.object');
expect(result).toEqual({
hi: "Hi",
hey: "Hey"
});
/* When querying an object that should be transpiled */
result = this.translocoService.translateObject('path.to.object', {
welcome: { value: 'John' },
'nested.subscribe': { price: 100 }
});
expect(result).toEqual({
welcome: "Welcome John",
nested: {
"subscribe": "subscribe today for 100$"
}});
}
}
  • Given a key: params map (object | Map), returns an array of translated values:
app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService) {}
ngOnInit() {
/* If there are no parameters to transpile pass an empty `object` or `null` */
let keyParams = {
home: null, // {}
}
let result = this.translocoService.translateObject(keyParams);
expect(result).toEqual(["Home"]);
/* When querying an object that should be transpiled */
keyParams = {
home: null,
hello: { name: 'John' },
}
result = this.translocoService.translateObject(keyParams);
expect(result).toEqual(["Home", "Hello John"]);
/* Works with object paths */
keyParams = {
hello: { name: 'John' },
'path.to.object.nested': {subscribe: {price: 100}}
}
result = this.translocoService.translateObject(keyParams);
expect(result).toEqual([ "Home", { subscribe: "subscribe today for 100$" }]);
/* Works with `Map` */
keyParams = new Map();
keyParams.set('home', null);
result = this.translocoService.translateObject(keyParams);
expect(result).toEqual(["Home"]);
}
}

selectTranslationObject()

Load the translation file (if not loaded yet) and behaves the same as translateObject. The only difference is that this method returns an observable to which you can subscribe.

The following code is based on the en.json in translateObject ☝

app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService) {}
ngOnInit() {
this.translocoService.selectTranslateObject('path.to.object', {
welcome: { value: 'John' },
'nested.subscribe': { price: 100 }
}).subscribe(result => {
expect(result).toEqual({
welcome: "Welcome John",
nested: {
"subscribe": "subscribe today for 100$"
}
});
});
keyParams = {
hello: { name: 'John' },
'path.to.object.nested': {subscribe: {price: 100}}
}
this.translocoService.selectTranslateObject(keyParams)
.subscribe(result => {
expect(result).toEqual(["Home", { subscribe: "subscribe today for 100$" }]);
});
}
}

getTranslation()

Returns the selected language translation or, if a language isn't passed, all of them:

app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService) {}
ngOnInit() {
this.translocoService.getTranslation();
this.translocoService.getTranslation('es');
}
}

selectTranslation()

Load and returns the active language translation object:

app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService) {}
ngOnInit() {
this.translocoService.selectTranslation()
.subscribe(console.log);
this.translocoService.selectTranslation('es')
.subscribe(console.log);
}
}

setTranslation()

Manually sets a translations object to be used for a given language, set merge to true if you want to append the translations instead of replacing them:

app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService) {}
ngOnInit() {
this.translocoService.setTranslation({ key: value });
this.translocoService.setTranslation({ ... }, 'es');
this.translocoService.setTranslation({ ... }, 'en', { merge: false } );
// Set a scope
this.translocoService.setTranslation({ ... }, 'todos/en');
}
}

setTranslationKey()

Sets the translated value of a key. If a language isn't specified in the third parameter, it sets the key value for the current active language:

app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService) {}
ngOnInit() {
this.translocoService.setTranslationKey('key', 'value');
this.translocoService.setTranslationKey('key.nested', 'value');
this.translocoService.setTranslationKey('key', 'value', 'en');
}
}

events$

Subscribe to the translation loading events:

app.component.ts
export class AppComponent {
constructor(private translocoService: TranslocoService) {}
ngOnInit() {
this.translocoService.events$.pipe(
filter(e => e.type === 'translationLoadSuccess'),
pluck('payload')
).subscribe(({ langName, scope }) => ...);
translocoService.events$.pipe(
filter(e => e.type === 'translationLoadFailure'),
pluck('payload')
).subscribe(({ langName, scope }) => ...);
}
Edit this page