Installation

To use Tolgee in your Angular application, you need to follow these steps:

1. Install the Tolgee integration library
2. Configure the Tolgee provider
3. Import Tolgee in standalone components
4. Set up the environment variables
5. Preparing for production

Install the Tolgee integration library

To install Tolgee integration library, run the following command:

npm

npm install @tolgee/ngx

yarn

yarn add @tolgee/ngx

pnpm

pnpm install @tolgee/ngx

Configure the Tolgee provider

Once the library is installed, register Tolgee in your application config with provideTolgee.

The setup can look like this:

import { ApplicationConfig } from '@angular/core';
import { environment } from '../environments/environment';
import {
  DevTools,
  FormatSimple,
  LanguageDetector,
  LanguageStorage,
  Tolgee,
  provideTolgee,
} from '@tolgee/ngx';

export const appConfig: ApplicationConfig = {
  providers: [
    provideTolgee(() =>
      Tolgee()
        .use(DevTools())
        .use(LanguageDetector())
        .use(LanguageStorage())
        .use(FormatSimple())
        // replace with .use(FormatIcu()) for plurals and formatted numbers
        .init({
          availableLanguages: ['en', 'cs'],
          defaultLanguage: 'en',
          fallbackLanguage: 'en',

          // for development
          apiKey: environment.tolgeeApiKey,
          apiUrl: environment.tolgeeApiUrl, // defaults to https://app.tolgee.io

          // for production
          staticData: {
            en: () => import('../i18n/en.json').then((m) => m.default),
            cs: () => import('../i18n/cs.json').then((m) => m.default),
          },
        })
    ),
  ],
};

The above code does the following:

• Registers Tolgee during application bootstrap using provideTolgee
• Provides TranslateService and starts Tolgee automatically through an app initializer
• Configures the Tolgee instance with your language settings, static data, and optional plugins such as DevTools, LanguageDetector, and LanguageStorage

You can configure more options and plugins during initialization. Learn about the available options and Tolgee plugins.

Import Tolgee in standalone components

TranslatePipe and TDirective are standalone Angular primitives. Import them in each component where you use them. It is the best practice to not combine multiple translation approaches within the app or component templates.

import { Component } from '@angular/core';
import { TranslatePipe } from '@tolgee/ngx';

@Component({
  template: `<h1>{{ 'hello_world' | translate }}</h1>`,
  imports: [TranslatePipe],
})
export class PipeExampleComponent {}

import { Component } from '@angular/core';
import { TDirective } from '@tolgee/ngx';

@Component({
  template: `<p t key="providing_default_values"></p>`,
  imports: [TDirective],
})
export class DirectiveExampleComponent {}

If you need imperative translations or language switching in component code, inject TranslateService.

import { Component, inject } from '@angular/core';
import { TranslateService } from '@tolgee/ngx';

@Component({
  template: `{{ currentLanguage }}`,
})
export class LanguageSwitcherComponent {
  private readonly translateService = inject(TranslateService);

  currentLanguage = this.translateService.language;

  async switchToCzech() {
    await this.translateService.changeLanguage('cs');
    this.currentLanguage = this.translateService.language;
  }
}

Set up the environment variables

Follow the instructions in Angular's environment configuration docs to configure apiUrl and apiKey.

Preparing for production

Tolgee will automatically omit DevTools from your bundle when you build your app for production. So it won't fetch translations directly from Tolgee Platform and it won't allow users to modify translations.

There are generally two ways how to use translations in production:

• Tolgee Content Delivery - translations are loaded dynamically from fast and reliable storage
• Providing localization files directly - your translations are bundled with your code

In production mode, you should never use localization data directly from Tolgee REST API, because it can negatively affect your page performance.

tip

You can also check the Angular example application to learn more.