---
title: "Translations — Angular"
description: "Show your viewer in the user's language: pick it, load its strings only when needed, add your own, and support right-to-left languages."
framework: "Angular"
source: "https://www.embedpdf.com/docs/headless/angular/ui/translations"
---

# Translations

The translations plugin holds your viewer's text in every language you support, and switches between
them while the app runs. Register it with the user's language:

**`i18n-plugin.ts`**

```typescript
import { Component } from '@angular/core';
import { negotiateLocale, withI18n } from '@embedpdf/angular/i18n';
import { provideEmbedPdf } from '@embedpdf/angular/runtime';
import en from './locales/en';
import { engine } from './pdf';

const locale = negotiateLocale(['en', 'nl', 'de'], navigator.languages) ?? 'en';

@Component({
  selector: 'app-document-viewer',
  providers: [
    provideEmbedPdf(
      { engine },
      /* … */
      withI18n({
        locale,
        locales: [{ code: 'en', name: 'English', translations: en }],
        loaders: {
          nl: () => import('./locales/nl').then((module) => module.default),
          de: () => import('./locales/de').then((module) => module.default),
        },
      }),
    ),
  ],
  template: `<!-- your toolbar and pages -->`,
})
export class DocumentViewer {}
```

Then translate with the `epdfT` pipe:

**`save-button.ts`**

```typescript
import { Component } from '@angular/core';
import { EpdfTPipe } from '@embedpdf/angular/i18n';

@Component({
  selector: 'app-save-button',
  imports: [EpdfTPipe],
  template: `<button>{{ 'toolbar.save' | epdfT }}</button>`,
})
export class SaveButton {}
```

`negotiateLocale` picks the best language you have for what the browser asks, such as `nl` for a
browser set to `nl-BE`, within the script it's written in: `zh-TW` doesn't get `zh-CN`, since
Taiwan writes Traditional Chinese and `zh-CN` is Simplified. A language in `loaders` is loaded the first time someone switches to it, so
your bundle carries only the one you start with.

## Strings

A language's `translations` are your strings, grouped however you like:

```ts
export default {
  toolbar: { save: 'Opslaan', zoomIn: 'Inzoomen' },
  search: {
    results: { one: '{count} resultaat', other: '{count} resultaten' },
  },
};
```

```ts
t('toolbar.save'); // 'Opslaan'
t('search.results', { params: { count: 3 } }); // '3 resultaten'
```

In a template, the pipe takes the same options: `{{ 'search.results' | epdfT: { params: { count: 3 } } }}`.

- **`{name}`** is filled in from `params`.
- **Plurals**: a string with `one` and `other` picks by `params.count`.
- **Missing strings** fall back to the fallback language (English unless you set another), then to
  `fallback` if you pass one, then to the key itself. You get a warning in the console once, so you
  notice.

## Switch the language

**`language-picker.ts`**

```typescript
import { Component, inject } from '@angular/core';
import { EpdfI18n } from '@embedpdf/angular/i18n';

@Component({
  selector: 'app-language-picker',
  template: `
    <select #picker [disabled]="i18n.loading() !== null" (change)="i18n.setLocale(picker.value)">
      @for (language of i18n.locales(); track language.code) {
        <option [value]="language.code" [selected]="language.code === i18n.locale()">
          {{ language.name }}
        </option>
      }
    </select>
  `,
})
export class LanguagePicker {
  protected readonly i18n = inject(EpdfI18n);
}
```

**`basic.ts`**

```typescript
import { ChangeDetectionStrategy, Component, inject, ViewEncapsulation } from '@angular/core';
import { EpdfDocumentGate, provideEmbedPdf } from '@embedpdf/angular/runtime';
import type { OpenInput } from '@embedpdf/angular/runtime';
import { EpdfPageTemplate, EpdfStage, withStage } from '@embedpdf/angular/stage';
import { EpdfRenderLayer, withRender } from '@embedpdf/angular/render';
import { EpdfCommand, standardCommands, withCommands } from '@embedpdf/angular/commands';
import { EpdfI18n, EpdfTPipe, withI18n } from '@embedpdf/angular/i18n';
import type { Locale } from '@embedpdf/angular/i18n';
import { localEngine } from '@embedpdf/engine';

// Your strings. The buttons' labels are the standard commands', which come translated.
const en: Locale = {
  code: 'en',
  name: 'English',
  translations: {
    app: { language: 'Language', pages: { one: '{count} page', other: '{count} pages' } },
  },
};
const nl: Locale = {
  code: 'nl',
  name: 'Nederlands',
  translations: {
    app: { language: 'Taal', pages: { one: '{count} pagina', other: "{count} pagina's" } },
  },
};

const ebook = async (): Promise<OpenInput> => {
  const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
  return { kind: 'bytes', id: 'ebook', bytes: new Uint8Array(await response.arrayBuffer()) };
};

@Component({
  selector: 'demo-root',
  imports: [EpdfDocumentGate, EpdfStage, EpdfPageTemplate, EpdfRenderLayer, EpdfCommand, EpdfTPipe],
  providers: [
    provideEmbedPdf(
      { engine: () => localEngine(), initialDocuments: [{ source: ebook }] },
      withStage(),
      withRender(),
      withCommands({ commands: standardCommands }),
      withI18n({
        locale: 'nl',
        locales: [en, nl],
        // Loaded the first time someone picks them; in your app, `() => import('./locales/de')`.
        loaders: {
          de: async () => ({
            code: 'de',
            name: 'Deutsch',
            translations: {
              app: { language: 'Sprache', pages: { one: '{count} Seite', other: '{count} Seiten' } },
            },
          }),
          ja: async () => ({
            code: 'ja',
            name: '日本語',
            translations: { app: { language: '言語', pages: { other: '{count} ページ' } } },
          }),
        },
      }),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './basic.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ng-container *epdfDocumentGate="let document; fallback: loading">
      <div class="toolbar">
        <label class="picker">
          {{ 'app.language' | epdfT }}
          <select
            #picker
            class="select"
            [disabled]="i18n.loading() !== null"
            (change)="i18n.setLocale(picker.value)"
          >
            @for (language of i18n.locales(); track language.code) {
              <option [value]="language.code" [selected]="language.code === i18n.locale()">
                {{ language.name }}
              </option>
            }
          </select>
        </label>
        @for (id of commands; track id) {
          <button type="button" class="button" [epdfCommand]="id" #command="epdfCommand">
            {{ command.label() }}
          </button>
        }
        <output class="count">
          {{ 'app.pages' | epdfT: { params: { count: stage.pageCount() } } }}
        </output>
      </div>
      <epdf-stage #stage="epdfStage" class="stage">
        <ng-template epdfPage>
          <epdf-render-layer />
        </ng-template>
      </epdf-stage>
    </ng-container>

    <ng-template #loading><p class="loading">…</p></ng-template>
  `,
})
export class App {
  // The component that provides the viewer can inject its services itself.
  protected readonly i18n = inject(EpdfI18n);
  protected readonly commands = ['page:previous', 'page:next', 'zoom:in', 'document:print'];
}
```

**`basic.css`**

```css
/* Colors */
:root {
  --ink: #1a2748;
  --muted: #5a6b92;
  --line: #e6eaf2;
  --line-strong: #dce8fc;
  --surface: #ffffff;
  --tint: #f3f7fe;
  --canvas: #f7f9fc;
  --focus: #7db6ff;
  --shadow: rgb(7 32 76 / 0.04);
}

/* The language picker and the buttons, above the pages; they wrap on a phone */
.toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 8px;
  margin-bottom: 14px;
}

.picker {
  display: inline-flex;
  align-items: center;
  gap: 8px;
  font-size: 13px;
  font-weight: 550;
  color: var(--muted);
}

.select {
  font: inherit;
  font-size: 13px;
  color: var(--ink);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 9px;
  padding: 7px 8px;
}

.select:focus-visible {
  outline: 2px solid var(--focus);
  outline-offset: 2px;
}

.button {
  font: inherit;
  font-size: 13px;
  font-weight: 550;
  line-height: 1;
  color: var(--ink);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 9px;
  padding: 8px 10px;
  cursor: pointer;
  box-shadow: 0 1px 2px var(--shadow);
}

.button:hover {
  background: var(--tint);
  border-color: var(--line-strong);
}

.button:focus-visible {
  outline: 2px solid var(--focus);
  outline-offset: 2px;
}

.button:disabled {
  opacity: 0.45;
  cursor: not-allowed;
}

.count {
  margin-inline-start: auto;
  font-size: 13px;
  color: var(--muted);
  font-variant-numeric: tabular-nums;
}

/* The pages */
.stage {
  height: 420px;
  border: 1px solid var(--line);
  border-radius: 14px;
  background: var(--canvas);
  box-shadow:
    0 1px 2px var(--shadow),
    0 18px 40px -28px rgb(7 32 76 / 0.28);
}

.loading {
  margin: 0;
  padding: 24px 0;
  text-align: center;
  font-size: 13px;
  color: var(--muted);
}
```

`setLocale()` loads the language if it needs to, then switches. Every `epdfT` pipe updates to the new
language.

## Add strings later

For a plugin of your own, or strings from your server, add them to a language while the app runs:

```ts
i18n.addTranslations('nl', { review: { approve: 'Goedkeuren' } });
i18n.addTranslations('nl', { 'review.reject': 'Afwijzen' }); // a dotted key works too
```

`registerLocale()` adds a whole new language, and returns a function that removes it again.

## EmbedPDF's own text

Commands have labels, and the [standard commands](commands#the-standard-commands) come translated in
English, Dutch, German, French, Spanish, Chinese, Swedish and Japanese, the languages of the standard
stamps. Change any of them with `addTranslations`, under the same keys.

## Right-to-left languages

A language can say it reads right to left with `direction: 'rtl'`. `direction` in [State](#state) tells
you, so you can set it on your viewer's root:

**`direction.ts`**

```typescript
import { Component, inject } from '@angular/core';
import { EpdfI18n } from '@embedpdf/angular/i18n';

@Component({
  selector: 'app-viewer-root',
  template: `
    <div [dir]="i18n.direction()">
      <!-- your viewer -->
    </div>
  `,
})
export class ViewerRoot {
  protected readonly i18n = inject(EpdfI18n);
}
```

**`rtl.ts`**

```typescript
import { ChangeDetectionStrategy, Component, inject, ViewEncapsulation } from '@angular/core';
import { EpdfDocumentGate, provideEmbedPdf } from '@embedpdf/angular/runtime';
import type { OpenInput } from '@embedpdf/angular/runtime';
import { EpdfPageTemplate, EpdfStage, withStage } from '@embedpdf/angular/stage';
import { EpdfRenderLayer, withRender } from '@embedpdf/angular/render';
import { EpdfCommand, standardCommands, withCommands } from '@embedpdf/angular/commands';
import { EpdfI18n, EpdfTPipe, withI18n } from '@embedpdf/angular/i18n';
import type { Locale } from '@embedpdf/angular/i18n';
import { localEngine } from '@embedpdf/engine';

const en: Locale = {
  code: 'en',
  name: 'English',
  translations: { app: { title: 'The ebook', switchTo: 'العربية' } },
};
// Arabic reads right to left. The standard commands have no Arabic labels, so the app gives
// them, under the same keys.
const ar: Locale = {
  code: 'ar',
  name: 'العربية',
  direction: 'rtl',
  translations: {
    app: { title: 'الكتاب الإلكتروني', switchTo: 'English' },
    commands: {
      page: { previous: 'الصفحة السابقة', next: 'الصفحة التالية' },
      zoom: { in: 'تكبير', out: 'تصغير' },
    },
  },
};

const ebook = async (): Promise<OpenInput> => {
  const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
  return { kind: 'bytes', id: 'ebook', bytes: new Uint8Array(await response.arrayBuffer()) };
};

// The toolbar follows the language: in Arabic it runs from right to left.
@Component({
  selector: 'demo-root',
  imports: [EpdfDocumentGate, EpdfStage, EpdfPageTemplate, EpdfRenderLayer, EpdfCommand, EpdfTPipe],
  providers: [
    provideEmbedPdf(
      { engine: () => localEngine(), initialDocuments: [{ source: ebook }] },
      withStage(),
      withRender(),
      withCommands({ commands: standardCommands }),
      withI18n({ locale: 'ar', locales: [en, ar] }),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './rtl.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <div *epdfDocumentGate="let document; fallback: loading" [dir]="i18n.direction()" class="root">
      <div class="toolbar">
        <strong class="title">{{ 'app.title' | epdfT }}</strong>
        @for (id of commands; track id) {
          <button type="button" class="button" [epdfCommand]="id" #command="epdfCommand">
            {{ command.label() }}
          </button>
        }
        <button type="button" class="button switch" (click)="switchLanguage()">
          {{ 'app.switchTo' | epdfT }}
        </button>
      </div>
      <epdf-stage class="stage">
        <ng-template epdfPage>
          <epdf-render-layer />
        </ng-template>
      </epdf-stage>
    </div>

    <ng-template #loading><p class="loading">…</p></ng-template>
  `,
})
export class App {
  protected readonly i18n = inject(EpdfI18n);
  protected readonly commands = ['page:previous', 'page:next', 'zoom:out', 'zoom:in'];

  protected switchLanguage() {
    void this.i18n.setLocale(this.i18n.locale() === 'ar' ? 'en' : 'ar');
  }
}
```

**`rtl.css`**

```css
/* Colors */
:root {
  --ink: #1a2748;
  --muted: #5a6b92;
  --line: #e6eaf2;
  --line-strong: #dce8fc;
  --surface: #ffffff;
  --tint: #f3f7fe;
  --canvas: #f7f9fc;
  --accent: #054fb3;
  --focus: #7db6ff;
  --shadow: rgb(7 32 76 / 0.04);
}

/* The toolbar, above the pages. Its spacing uses start and end, not left and right, so it
   mirrors itself in a right-to-left language; it wraps on a phone */
.toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 8px;
  margin-bottom: 14px;
}

.title {
  margin-inline-end: 6px;
  font-size: 14px;
  color: var(--ink);
}

.button {
  font: inherit;
  font-size: 13px;
  font-weight: 550;
  line-height: 1;
  color: var(--ink);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 9px;
  padding: 8px 10px;
  cursor: pointer;
  box-shadow: 0 1px 2px var(--shadow);
}

.button:hover {
  background: var(--tint);
  border-color: var(--line-strong);
}

.button:focus-visible {
  outline: 2px solid var(--focus);
  outline-offset: 2px;
}

.button:disabled {
  opacity: 0.45;
  cursor: not-allowed;
}

/* The language switch sits at the end: on the right in English, on the left in Arabic */
.switch {
  margin-inline-start: auto;
  color: var(--accent);
}

/* The pages */
.stage {
  height: 420px;
  border: 1px solid var(--line);
  border-radius: 14px;
  background: var(--canvas);
  box-shadow:
    0 1px 2px var(--shadow),
    0 18px 40px -28px rgb(7 32 76 / 0.28);
}

.loading {
  margin: 0;
  padding: 24px 0;
  text-align: center;
  font-size: 13px;
  color: var(--muted);
}
```

For documents that read right to left, such as a book in Arabic, set the Stage's `direction` too, so
pages and spreads run from right to left.

## Methods

Everything `inject(EpdfI18n)` gives you.

| Method                                                        | What it does                                                                                                                                                                        |
| :------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `t(key, { params?, fallback? })`                              | A string in the current language, with `params` filled in. In a template, use the `epdfT` pipe, which updates when the language changes. [Strings](#strings)                        |
| `getTranslator()`                                             | A `t` function that stays the same until the language or the strings change, for code that caches on it.                                                                            |
| `hasKey(key)`                                                 | Whether a key has a string in the current or the fallback language. Never warns.                                                                                                    |
| `setLocale(code)`                                             | Loads the language if it needs to, then switches. Resolves once it shows; rejects when it can't load, or when a newer call replaces it. [Switch the language](#switch-the-language) |
| `addTranslations(code, translations)`                         | Adds strings to one of your languages, loaded or not, and replaces the ones with the same key. [Add strings later](#add-strings-later)                                              |
| `registerLocale(locale)`                                      | Adds a whole language, `{ code, name, direction?, translations }`, and returns a function that removes it again                                                                     |
| `getSettings()`, `updateSettings(changes)`, `resetSettings()` | Reads the settings, changes them while the app runs, or goes back to what you registered. In a component, use `inject(EpdfI18n).settings()`. [Settings](#settings)                  |

Every method that returns a promise also takes a `signal` in its options, to cancel it.

## State

Every value is a signal on `inject(EpdfI18n)`: read it in a template or a `computed()`, and your view updates when it changes. The method in the last column reads the same value once.

| Field         | What it is                                                                                                                                                                   | Read once            |
| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
| `locale()`    | The current language's code                                                                                                                                                  | `getLocale()`        |
| `direction()` | `'ltr'` or `'rtl'`, how the current language reads                                                                                                                           | `getDirection()`     |
| `locales()`   | Every language you can switch to, loaded or not, each with `code`, `name`, `direction` and `loaded`. A language in `loaders` shows its code as its `name` until it's loaded. | `listLocales()`      |
| `loading()`   | The code of the language being loaded, or `null`                                                                                                                             | `getLoadingLocale()` |

## Settings

Set them when you register the plugin, and change them while the app runs with
`i18n.updateSettings({ … })`; `i18n.resetSettings()` goes back to what you registered, and
`inject(EpdfI18n).settings()` gives you the current settings.

| Setting          | What it does                                            | Default          |
| :--------------- | :------------------------------------------------------ | :--------------- |
| `locale`         | The language to start with                              | `fallbackLocale` |
| `fallbackLocale` | The language to use for strings another language misses | `'en'`           |
| `locales`        | Languages loaded from the start                         | none             |
| `loaders`        | Languages loaded when someone switches to them          | none             |

## Events

**`locale-events.ts`**

```typescript
import { Component, DOCUMENT, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { EpdfI18n } from '@embedpdf/angular/i18n';

@Component({
  selector: 'app-viewer-layout',
  template: `<!-- your toolbar and pages -->`,
})
export class ViewerLayout {
  private readonly i18n = inject(EpdfI18n);
  private readonly document = inject(DOCUMENT);

  constructor() {
    this.i18n.localeChanged$
      .pipe(takeUntilDestroyed())
      .subscribe(({ locale }) => this.document.documentElement.setAttribute('lang', locale));
  }
}
```

| Event               | Fires when                    | Carries                    |
| :------------------ | :---------------------------- | :------------------------- |
| `localeChanged$`    | The language changed          | `locale`, `previousLocale` |
| `localeLoadFailed$` | A language couldn't be loaded | `locale`, `error`          |
| `settingsChanged$`  | The settings changed          | `settings`, `changed`      |

## Good to know

### Before a document opens

The plugin needs no engine and no document, so your loading screen, a password prompt and an empty
viewer can be translated too.

### A language that fails to load

When a language in `loaders` can't be loaded, for example because the user is offline, the viewer
stays in the language it had, and `localeLoadFailed$` tells you why. Call `setLocale()` again to
try once more.