Translations
The viewer speaks the user’s language: it picks the best match from the browser’s languages. To
choose one yourself, set locale:
{ locale: 'de' }locale follows its prop, so a language switch in your app switches the viewer too. Without it,
or with 'auto', the viewer follows the browser, and shows the
fallback language when the browser asks for none of its languages.
The languages it speaks#
English, German, French, Spanish, Italian, Dutch, Portuguese, Polish, Swedish, Japanese, Chinese
(Simplified and Traditional), Korean, Arabic and Hebrew. Each one loads only when it’s needed. For
Arabic and Hebrew, the viewer is right-to-left: the bars mirror, and start and end swap sides.
A language matches in its own script: readers in Taiwan and Hong Kong (zh-TW, zh-HK) see
Traditional Chinese, and readers in China and Singapore (zh-CN, zh-SG) Simplified.
Dates, times and numbers are written in the language on screen, the way the reader’s region
writes them: a comment in English reads 14 Sept, 17:30 in a British browser and
Sep 14, 5:30 PM in an American one. A locale that names a region, such as 'en-GB', writes
them that way for everyone.
Change a word#
A built-in button’s label has the command’s id as its key. Give a new one, per language:
{
strings: {
en: { 'document:download': 'Save a copy' },
de: { 'document:download': 'Kopie speichern' },
},
}A panel’s button and the title in its header are one word, under the button’s command id:
'panel:comments' renames both. See Panels.
A mode tab is a button too, with the command mode:annotate for Annotate. Here a picker in your
app sets locale, and strings gives two labels your own words in each language it offers:
Loading live preview…
import { useState } from 'react';
import { PDFViewer } from '@embedpdf/viewer-react';
import './languages.css';
const welcome = 'https://www.embedpdf.com/pdfs/welcome.pdf';
// Your own words for two of the viewer's labels, in each language.
const strings = {
en: { 'mode:annotate': 'Review', 'document:download': 'Save a copy' },
de: { 'mode:annotate': 'Prüfen', 'document:download': 'Kopie speichern' },
fr: { 'mode:annotate': 'Relire', 'document:download': 'Enregistrer une copie' },
nl: { 'mode:annotate': 'Nakijken', 'document:download': 'Kopie opslaan' },
ar: { 'mode:annotate': 'مراجعة', 'document:download': 'حفظ نسخة' },
};
export default function App() {
const [locale, setLocale] = useState('en');
return (
<div className="app">
<header className="bar">
<select
aria-label="Language"
value={locale}
onChange={(event) => setLocale(event.target.value)}
>
<option value="en">English</option>
<option value="de">Deutsch</option>
<option value="fr">Français</option>
<option value="nl">Nederlands</option>
<option value="ar">العربية</option>
</select>
</header>
<PDFViewer className="viewer" src={welcome} strings={strings} locale={locale} />
</div>
);
}Try it: the second tab reads Review instead of Annotate, and the menu at the top left has Save a copy. Pick Deutsch above the viewer: every word changes, yours too. Pick العربية and the bars mirror.
Translate your own buttons#
Give a command a labelKey, and its words per language:
{
commands: [
{ id: 'acme:send', labelKey: 'acme.send', label: 'Send for signature', icon: 'signature', run: send },
],
strings: {
en: { 'acme.send': 'Send for signature' },
nl: { 'acme.send': 'Verstuur ter ondertekening' },
},
}The label shows when no language has the word, so give it too. Panels and mode bars take a
titleKey the same way, for their title. A panel’s title is its
button’s label too.
The style panel’s words have keys too: each property and option by what it says
(annotation.style.stroke, annotation.style.opacity, annotation.lineEndings.openArrow), and a
form field’s settings by theirs (form.settings.tooltip). Change one like any other word:
{ strings: { en: { 'annotation.style.stroke': 'Line' } } }So do the page number’s words, under pageNumber., and the comments panel’s, under comments..
The ones you’re most likely to change:
| Key | What it says |
|---|---|
pageNumber.page | {current} / {total} |
pageNumber.pages | {first}–{last} / {total}, while a spread fits across the view (spread) |
pageNumber.goToPage | The tooltip of the page number, and the label of the field it turns into |
comments.empty, comments.emptyReadOnly | What the panel says while the document has no comments, when the user can add some and when not |
comments.addPlaceholder, comments.replyPlaceholder, comments.reply | The field for a new comment, and for a reply |
comments.statusAccepted, comments.statusRejected, comments.statusCancelled, comments.statusCompleted, comments.statusNone | A thread’s status |
A word in braces is filled in as the viewer writes it: keep it in your words. The number that turns
into a field to type a page is {current}, or {first}:
{ strings: { en: { 'pageNumber.page': 'Page {current} of {total}', 'comments.empty': 'No notes yet.' } } }A language of your own#
Give strings for a language the viewer doesn’t have, and it becomes one of its languages. Anything
you don’t translate shows in the fallback language, English unless
you set another:
{
locale: 'da',
strings: { da: { 'document:download': 'Hent', 'zoom:in': 'Zoom ind' } },
}It reads right to left when its code says so: a right-to-left language such as fa or ur, or a
right-to-left script such as ku-Arab.
Load words when they’re needed#
Give a language’s words as a function, and they load the first time the viewer shows that language, so a page in Swedish never downloads your Danish:
{
strings: {
sv: () => import('./strings/sv.json'),
da: () => import('./strings/da.json'),
},
}The viewer shows the language once its words are in, and English until then. The function returns
the words, or a module whose default export is the words, which is what import() of a JSON file
gives you. Without a bundler, fetch the file instead:
sv: () => fetch('/strings/sv.json').then((response) => response.json()).
Fall back to another language#
The fallback language is the one the viewer shows when the browser asks for none of its languages, and the one a word comes from when the current language doesn’t have it. It’s English unless you set another:
{
strings: {
sv: { 'acme.send': 'Skicka för signering', 'acme.archive': 'Arkivera' },
da: { 'acme.send': 'Send til underskrift' },
},
plugins: { i18n: { fallbackLocale: 'sv' } },
}A reader in Denmark sees your Danish, and Swedish for everything you didn’t translate into Danish: Arkivera, and every word of the viewer’s own. A reader in Finland, which the viewer has no language for, sees Swedish. The fallback language can be one of the viewer’s languages or one of yours, and it loads at the start, so no word waits for it.
Translate the whole viewer#
Every word the viewer shows is in English in @embedpdf/viewer/strings/en.json, in the shape
strings takes. Copy it, translate it, and give it as a language of your own:
{
locale: 'da',
strings: { da: () => import('./strings/da.json') },
}Download it from jsDelivr, or import it from the package. Any word you leave out shows in the fallback language.
Good to know#
Change the language from code#
viewer.get('i18n').setLocale('fr') does the same as the locale prop, and returns a promise that
resolves once the language has loaded.
Add words while the app runs#
viewer.get('i18n').addTranslations('nl', { … }) adds or replaces words in a language without
starting over, for words that arrive from your own translation service.
Labels in the toolbar#
The toolbar measures the words it shows, so a longer translation moves fewer or more buttons into the “More” menu by itself.
Your feedback goes directly to the documentation team.