Translation API

A list of the TranslocoService API methods and their usages

Check out the new signal translation API 🚦

translate()

Translate a given key, allowing optional parameters for dynamic values or language specification. Use this method when you need to translate keys directly in components or services.

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 Ensure translation files are loaded before calling this method. Otherwise, use selectTranslate().

---

selectTranslate()

Returns an observable that emits translations. It loads the required translation file automatically.

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

  ngOnInit() {
    this.translocoService.selectTranslate('hello').subscribe(value => ...);
    this.translocoService.selectTranslate('hello', params).subscribe(value => ...);
    this.translocoService.selectTranslate('hello', params, 'es').subscribe(value => ...);
  }
}

• Automatically updates when the active language changes.

• Supports scoped translations via TRANSLOCO_SCOPE.

---

translateObject()

Retrieve a nested object or an array of translated values based on keys.

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

    result = this.translocoService.translateObject('path.to.object', {
      welcome: { name: 'John' },
      'nested.subscribe': { price: 100 },
    });
    expect(result).toEqual({
      welcome: 'Welcome John',
      nested: { subscribe: 'subscribe today for 100$' },
    });
  }
}

Important Ensure translation files are loaded before calling this method. Otherwise, use selectTranslateObject().

---

selectTranslateObject()

Similar to translateObject(), but returns an observable. It ensures the translation file is loaded.

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

  ngOnInit() {
    this.translocoService
      .selectTranslateObject('path.to.object', {
        welcome: { name: 'John' },
        'nested.subscribe': { price: 100 },
      })
      .subscribe(result => {
        expect(result).toEqual({
          welcome: 'Welcome John',
          nested: { subscribe: 'subscribe today for 100$' },
        });
      });
  }
}

---

getTranslation()

Retrieve the entire translation map for the active language or a specific language/scope.

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 emits the full translation map for the specified language or scope.

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

  ngOnInit() {
    this.translocoService.selectTranslation('es').subscribe(console.log);
    this.translocoService.selectTranslation('todos/es').subscribe(console.log);
    this.translocoService.selectTranslation().subscribe(console.log); // Updates on language change
  }
}

---

setTranslation()

Manually sets translation data for a language or scope. Use merge: true to append data.

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 });
    this.translocoService.setTranslation({ ... }, 'todos/en');
  }
}

---

setTranslationKey()

Set or update the value of a specific translation key.

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$

Listen to translation events, such as language changes or load failures.

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 === 'langChanged'), pluck('payload'))
      .subscribe(({ langName }) => ...);
  }
}

Important Events only fire when translations are loaded from the server, not from the cache.