---
title: "Translations — Svelte"
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: "Svelte"
source: "https://www.embedpdf.com/docs/headless/svelte/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.svelte`**

```svelte
<script lang="ts">
  import { i18nPlugin, negotiateLocale } from '@embedpdf/svelte/i18n';
  import { Viewer } from '@embedpdf/svelte/runtime';
  import en from './locales/en';
  import { engine } from './pdf';

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

  const plugins = [
    /* … */
    i18nPlugin({
      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),
      },
    }),
  ];
</script>

<Viewer {engine} {plugins}>
  <!-- your toolbar and pages -->
</Viewer>
```

Then translate with `useT()`:

**`save-button.svelte`**

```svelte
<script lang="ts">
  import { useT } from '@embedpdf/svelte/i18n';

  const t = useT();
</script>

<button>{t('toolbar.save')}</button>
```

`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'
```



- **`{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.svelte`**

```svelte
<script lang="ts">
  import { useI18n, useI18nState } from '@embedpdf/svelte/i18n';

  const i18n = useI18n();
  const state = useI18nState();
</script>

<select
  value={state.locale}
  disabled={state.loading !== null}
  onchange={(event) => i18n.setLocale(event.currentTarget.value)}
>
  {#each state.locales as language (language.code)}
    <option value={language.code}>{language.name}</option>
  {/each}
</select>
```

**`App.svelte`**

```svelte
<script lang="ts" module>
  import { DocumentGate, Viewer, type OpenInput } from '@embedpdf/svelte/runtime';
  import { RenderLayer, renderPlugin } from '@embedpdf/svelte/render';
  import { Stage, stagePlugin } from '@embedpdf/svelte/stage';
  import { commandsPlugin, standardCommands } from '@embedpdf/svelte/commands';
  import { i18nPlugin, type Locale } from '@embedpdf/svelte/i18n';
  import { localEngine } from '@embedpdf/engine';
  import CommandButton from './CommandButton.svelte';
  import LanguagePicker from './LanguagePicker.svelte';
  import PageCount from './PageCount.svelte';

  import '../basic.css';

  const engine = localEngine();

  // 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 plugins = [
    stagePlugin(),
    renderPlugin(),
    commandsPlugin({ commands: standardCommands }),
    i18nPlugin({
      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} ページ' } } },
        }),
      },
    }),
  ];

  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()) };
  };
</script>

<Viewer {engine} {plugins} initialDocuments={[{ source: ebook }]}>
  <DocumentGate>
    {#snippet fallback()}
      <p class="loading">…</p>
    {/snippet}
    <div class="toolbar">
      <LanguagePicker />
      <CommandButton id="page:previous" />
      <CommandButton id="page:next" />
      <CommandButton id="zoom:in" />
      <CommandButton id="document:print" />
      <PageCount />
    </div>
    <Stage class="stage">
      <RenderLayer />
    </Stage>
  </DocumentGate>
</Viewer>
```

**`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);
}
```

**`CommandButton.svelte`**

```svelte
<script lang="ts">
  import { useCommand } from '@embedpdf/svelte/commands';

  let { id }: { id: string } = $props();

  const command = useCommand(() => id);
</script>

{#if command.current.visible}
  {@const cmd = command.current}
  <button type="button" class="button" disabled={!cmd.enabled} onclick={cmd.run}>
    {cmd.label}
  </button>
{/if}
```

**`LanguagePicker.svelte`**

```svelte
<script lang="ts">
  import { useI18n, useI18nState, useT } from '@embedpdf/svelte/i18n';

  const i18n = useI18n();
  const t = useT();
  const state = useI18nState();
</script>

<label class="picker">
  {t('app.language')}
  <select
    class="select"
    value={state.locale}
    disabled={state.loading !== null}
    onchange={(event) => void i18n.setLocale(event.currentTarget.value)}
  >
    {#each state.locales as language (language.code)}
      <option value={language.code}>{language.name}</option>
    {/each}
  </select>
</label>
```

**`PageCount.svelte`**

```svelte
<script lang="ts">
  import { useStageState } from '@embedpdf/svelte/stage';
  import { useT } from '@embedpdf/svelte/i18n';

  const t = useT();
  const stageState = useStageState();
</script>

<output class="count">{t('app.pages', { params: { count: stageState.pageCount } })}</output>
```

`setLocale()` loads the language if it needs to, then switches. Everything that uses `useT()`
updates in 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.svelte`**

```svelte
<script lang="ts">
  import { useI18nState } from '@embedpdf/svelte/i18n';

  const state = useI18nState();
</script>

<div dir={state.direction}>
  <!-- your viewer -->
</div>
```

**`App.svelte`**

```svelte
<script lang="ts" module>
  import { DocumentGate, Viewer, type OpenInput } from '@embedpdf/svelte/runtime';
  import { renderPlugin } from '@embedpdf/svelte/render';
  import { stagePlugin } from '@embedpdf/svelte/stage';
  import { commandsPlugin, standardCommands } from '@embedpdf/svelte/commands';
  import { i18nPlugin, type Locale } from '@embedpdf/svelte/i18n';
  import { localEngine } from '@embedpdf/engine';
  import ViewerRoot from './ViewerRoot.svelte';

  import '../rtl.css';

  const engine = localEngine();

  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 plugins = [
    stagePlugin(),
    renderPlugin(),
    commandsPlugin({ commands: standardCommands }),
    i18nPlugin({ locale: 'ar', locales: [en, ar] }),
  ];

  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()) };
  };
</script>

<Viewer {engine} {plugins} initialDocuments={[{ source: ebook }]}>
  <DocumentGate>
    {#snippet fallback()}
      <p class="loading">…</p>
    {/snippet}
    <ViewerRoot />
  </DocumentGate>
</Viewer>
```

**`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);
}
```

**`CommandButton.svelte`**

```svelte
<script lang="ts">
  import { useCommand } from '@embedpdf/svelte/commands';

  let { id }: { id: string } = $props();

  const command = useCommand(() => id);
</script>

{#if command.current.visible}
  {@const cmd = command.current}
  <button type="button" class="button" disabled={!cmd.enabled} onclick={cmd.run}>
    {cmd.label}
  </button>
{/if}
```

**`ViewerRoot.svelte`**

```svelte
<!-- The toolbar follows the language: in Arabic it runs from right to left. -->
<script lang="ts">
  import { RenderLayer } from '@embedpdf/svelte/render';
  import { Stage } from '@embedpdf/svelte/stage';
  import { useI18n, useI18nState, useT } from '@embedpdf/svelte/i18n';
  import CommandButton from './CommandButton.svelte';

  const i18n = useI18n();
  const t = useT();
  const state = useI18nState();
</script>

<div dir={state.direction} class="root">
  <div class="toolbar">
    <strong class="title">{t('app.title')}</strong>
    <CommandButton id="page:previous" />
    <CommandButton id="page:next" />
    <CommandButton id="zoom:out" />
    <CommandButton id="zoom:in" />
    <button
      type="button"
      class="button switch"
      onclick={() => void i18n.setLocale(state.locale === 'ar' ? 'en' : 'ar')}
    >
      {t('app.switchTo')}
    </button>
  </div>
  <Stage class="stage">
    <RenderLayer />
  </Stage>
</div>
```

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 `useI18n()` gives you.

| Method                                                        | What it does                                                                                                                                                                        |
| :------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `t(key, { params?, fallback? })`                              | A string in the current language, with `params` filled in. In a component, use `useT()`, 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. `useT()` returns 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 `useI18nSettings()`. [Settings](#settings)                            |

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

## State

Everything `useI18nState()` gives you, as one reactive object: read its fields, and your markup updates when they change. 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
`useI18nSettings()` 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.svelte`**

```svelte
<script lang="ts">
  import { useI18nEvent } from '@embedpdf/svelte/i18n';

  useI18nEvent(
    (i18n) => i18n.onLocaleChanged,
    ({ locale }) => document.documentElement.setAttribute('lang', locale),
  );
</script>

<!-- your toolbar and pages -->
```

| Event                | Fires when                    | Carries                    |
| :------------------- | :---------------------------- | :------------------------- |
| `onLocaleChanged`    | The language changed          | `locale`, `previousLocale` |
| `onLocaleLoadFailed` | A language couldn't be loaded | `locale`, `error`          |
| `onSettingsChanged`  | 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 `onLocaleLoadFailed` tells you why. Call `setLocale()` again to
try once more.