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

```vue
<script setup lang="ts">
import { i18nPlugin, negotiateLocale } from '@embedpdf/vue/i18n';
import { Viewer } from '@embedpdf/vue/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>

<template>
  <Viewer :engine :plugins>
    <!-- your toolbar and pages -->
  </Viewer>
</template>
```

Then translate with `useT()`:

**`save-button.vue`**

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

const t = useT();
</script>

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

`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.vue`**

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

const i18n = useI18n();
const { locale, locales, loading } = useI18nState();

function onChange(event: Event) {
  i18n.setLocale((event.target as HTMLSelectElement).value);
}
</script>

<template>
  <select :value="locale" :disabled="loading !== null" @change="onChange">
    <option v-for="language in locales" :key="language.code" :value="language.code">
      {{ language.name }}
    </option>
  </select>
</template>
```

**`App.vue`**

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

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>

<template>
  <Viewer :engine="engine" :plugins="plugins" :initial-documents="[{ source: ebook }]">
    <DocumentGate>
      <template #fallback><p class="loading">…</p></template>
      <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">
        <template #page><RenderLayer /></template>
      </Stage>
    </DocumentGate>
  </Viewer>
</template>
```

**`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.vue`**

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

const props = defineProps<{ id: string }>();
const command = useCommand(() => props.id);
</script>

<template>
  <button
    v-if="command.visible"
    type="button"
    class="button"
    :disabled="!command.enabled"
    @click="command.run()"
  >
    {{ command.label }}
  </button>
</template>
```

**`LanguagePicker.vue`**

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

const i18n = useI18n();
const t = useT();
const { locale, locales, loading } = useI18nState();

function onChange(event: Event) {
  void i18n.setLocale((event.target as HTMLSelectElement).value);
}
</script>

<template>
  <label class="picker">
    {{ t('app.language') }}
    <select class="select" :value="locale" :disabled="loading !== null" @change="onChange">
      <option v-for="language in locales" :key="language.code" :value="language.code">
        {{ language.name }}
      </option>
    </select>
  </label>
</template>
```

**`PageCount.vue`**

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

const t = useT();
const { pageCount } = useStageState();
</script>

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

`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.vue`**

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

const { direction } = useI18nState();
</script>

<template>
  <div :dir="direction">
    <!-- your viewer -->
  </div>
</template>
```

**`App.vue`**

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

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>

<template>
  <Viewer :engine="engine" :plugins="plugins" :initial-documents="[{ source: ebook }]">
    <DocumentGate>
      <template #fallback><p class="loading">…</p></template>
      <ViewerRoot />
    </DocumentGate>
  </Viewer>
</template>
```

**`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.vue`**

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

const props = defineProps<{ id: string }>();
const command = useCommand(() => props.id);
</script>

<template>
  <button
    v-if="command.visible"
    type="button"
    class="button"
    :disabled="!command.enabled"
    @click="command.run()"
  >
    {{ command.label }}
  </button>
</template>
```

**`ViewerRoot.vue`**

```vue
<script setup lang="ts">
import { Stage } from '@embedpdf/vue/stage';
import { RenderLayer } from '@embedpdf/vue/render';
import { useI18n, useI18nState, useT } from '@embedpdf/vue/i18n';
import CommandButton from './CommandButton.vue';

// The toolbar follows the language: in Arabic it runs from right to left.
const i18n = useI18n();
const t = useT();
const { direction, locale } = useI18nState();
</script>

<template>
  <div :dir="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"
        @click="i18n.setLocale(locale === 'ar' ? 'en' : 'ar')"
      >
        {{ t('app.switchTo') }}
      </button>
    </div>
    <Stage class="stage">
      <template #page><RenderLayer /></template>
    </Stage>
  </div>
</template>
```

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 refs: your template updates when a value 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
`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.vue`**

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

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

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

| 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.