Skip to main content

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 loads the translation file and emits the translation of the given key:

app.component.ts
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  // Don't forget to unsubscribe
  ngOnInit() {
    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"]);
  }
}
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 selectTranslateObject() method instead:

selectTranslateObject()​

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 a scope translation, if a language isn't passed, the method will return the entire translation map:

app.component.ts
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  ngOnInit() {
    this.translocoService.getTranslation();
    this.translocoService.getTranslation('es');
    this.translocoService.getTranslation('todos/es');
  }
}

selectTranslation()​

Returns an observable that when subscribed loads and emits the given language translation object, if no language is passed the active language will be used.
This method can also be used to retrieve a scope translation object:

app.component.ts
export class AppComponent {
  constructor(private translocoService: TranslocoService) {}

  // Don't forget to unsubscribe
  ngOnInit() {
    this.translocoService.selectTranslation('es')
                         .subscribe(console.log);
                         
    this.translocoService.selectTranslation('todos/es')
                         .subscribe(console.log);
                                                                    
    // Will emit a new value on language changes.                     
    this.translocoService.selectTranslation()
                         .subscribe(console.log);
                                                         
    this.translocoService.selectTranslation('todos')
                         .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');
    this.translocoService.setTranslationKey('key', 'value', 'en', { emitChange: false });
  }
}

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 }) => ...);

    this.translocoService.events$.pipe(
      filter(e => e.type === 'translationLoadFailure'),
      pluck('payload')
    ).subscribe(({ langName, scope }) => ...);
    
    this.translocoService.events$.pipe(
      filter(e => e.type === 'langChanged'),
      pluck('payload')
    ).subscribe(({ langName, scope }) => ...);
}
important

Note that these events will only fire when the translation is loaded from the server, meaning that when switching from a given lang and back won't trigger the events again since the language is loaded from the cache.