API

The @tolgee/ngx package exports the Angular integration primitives listed below together with everything exported by @tolgee/web.

provideTolgee

Registers Tolgee in Angular's application dependency injection provider tree.

Use this as the default integration entry point. It:

• provides TOLGEE_INSTANCE
• provides TranslateService
• starts Tolgee automatically through an app initializer

The factory can return either a TolgeeInstance or a Promise<TolgeeInstance>.

import { ApplicationConfig } from '@angular/core';
import { FormatIcu } from '@tolgee/format-icu';
import {
  DevTools,
  LanguageDetector,
  LanguageStorage,
  Tolgee,
  provideTolgee,
} from '@tolgee/ngx';

export const appConfig: ApplicationConfig = {
  providers: [
    provideTolgee(() =>
      Tolgee()
        .use(LanguageDetector())
        .use(LanguageStorage())
        .use(FormatIcu())
        .use(DevTools())
        .init({
          staticData: {
            en: () => import('../i18n/en.json').then((m) => m.default),
            cs: () => import('../i18n/cs.json').then((m) => m.default),
          },
          defaultLanguage: 'en',
          fallbackLanguage: 'en',
        })
    ),
  ],
};

TranslateService

Provides imperative translation methods, language switching, and Tolgee event access.

property tolgee

The resolved Tolgee instance.

property language

Returns the current language as a string.

this.translateService.language; // "en"

property languageAsync

Returns an Observable<string> that emits the current language immediately and again whenever the language changes.

method changeLanguage

Changes the current language.

this.translateService.changeLanguage('en');

method translate

Returns an Observable<string> that emits the translated value and updates again when Tolgee data changes, for example after a language switch.

this.subscription = this.translateService
  .translate('this_is_a_key_with_params', 'Default value', { key: 'value' })
  .subscribe((val) => (this.translated = val));

This method accepts the same arguments as Tolgee.t.

translate(key: string, options?: CombinedOptions): Observable<string>
translate(key: string, defaultValue?: string, options?: CombinedOptions): Observable<string>
translate(props: TranslateProps): Observable<string>

method instant

Returns the current translation synchronously.

const translated = this.translateService.instant(
  'this_is_a_key_with_params',
  'Default value',
  { key: 'value' }
);

This method accepts the same arguments as Tolgee.t.

instant(key: string, options?: CombinedOptions): string
instant(key: string, defaultValue?: string, options?: CombinedOptions): string
instant(props: TranslateProps): string

method on

Listens to Tolgee events and emits them back inside Angular's NgZone, so Angular change detection continues to work as expected.

parameter event

The event to listen to.

Returns an Observable emitting event-specific data.

Read more in the Events API.

method start

Starts Tolgee and runs Tolgee.run() outside Angular's NgZone.

If you use provideTolgee, Angular calls this automatically during app initialization. You usually don't need to call it yourself.

TDirective (former TComponent)

Directive with selector [t]. It replaces the content of the host element with the translated value.

TDirective is standalone, so import it anywhere you use the t attribute.

• Input key - Key to translate
• Input ns - The namespace of the key
• Input params - Object of parameters to interpolate
• Input default - Default value
• Input isHtml - Whether the translated value should be rendered as HTML
• Input noWrap - Disable wrapping
• Input language - Override the current Tolgee language for a specific translation. Load the language manually with tolgee.loadRecord.

<div t key="this_is_a_key_with_params" [params]="{ key: 'value' }"></div>

translate pipe

Pipe that translates a key with optional params, default value, or translation props object.

TranslatePipe is standalone, so import it anywhere you use | translate.

Example usages:

{{ 'this_key_does_not_exist' | translate: 'This is default' }}

{{ 'key_with_params' | translate: { key: 'value', key2: 'value2' } }}

{{ 'key_with_params' | translate: 'Default value' : { key: 'value' } }}

{{ { key: 'this_is_a_key', defaultValue: 'Jeeey!' } | translate }}

namespaceResolver

Function-based Angular router resolver for loading namespaces before a lazy route renders.

Set data.tolgeeNamespace on the route and add namespaceResolver to resolve.

TOLGEE_INSTANCE

Injection token for the Tolgee instance.

In most applications, you DO NOT NEED to provide this token manually. provideTolgee does that for you.

The token type is TolgeeInstance | Promise<TolgeeInstance>, so if your provideTolgee factory is async the token may temporarily hold a promise until app initialization finishes.

import { inject } from '@angular/core';
import { TOLGEE_INSTANCE } from '@tolgee/ngx';

export function useTolgeeInstance() {
  return inject(TOLGEE_INSTANCE);
}