Labels and locale

Translate or reword every visible text and accessible name, and format numbers for any locale.

Basics

labels overrides any subset of the viewer’s texts and locale sets number formatting.

import { PdfViewer, type PdfViewerLabels } from '@kingtech/react-pdf-viewer'; // Defined once at module scope: labels are merged per object identity. const hungarian: Partial<PdfViewerLabels> = { viewer: 'PDF-megjelenítő', toolbar: 'PDF-vezérlők', zoomIn: 'Nagyítás', zoomOut: 'Kicsinyítés', previousPage: 'Előző oldal', nextPage: 'Következő oldal', enterFullscreen: 'Teljes képernyő', exitFullscreen: 'Kilépés a teljes képernyőből', rotate: 'Forgatás', download: 'Letöltés', print: 'Nyomtatás', moreActions: 'További műveletek', pageAriaLabel: (page, total, { formatNumber }) => `${formatNumber(page)}. oldal, összesen ${formatNumber(total)}`, }; export default function Demo() { return <PdfViewer source="/samples/multipage.pdf" locale="hu-HU" labels={hungarian} />; }

Keys you leave out keep their English defaults, exported as defaultLabels. Accessible names (the toolbar, buttons, the page image, the thumbnails sidebar) are labels too, so a translated viewer is fully translated for screen reader users.

Text and function labels

Most labels are strings. Labels that contain numbers are functions that receive the numbers and a { formatNumber } helper, so they read naturally in any language:

const labels = {
  pageIndicator: (page, total, { formatNumber }) =>
    `${formatNumber(page)} / ${formatNumber(total)}`,
  printProgress: (done, total) => `Preparing ${done} of ${total}…`,
};

Every key, its default and its purpose is listed in the PdfViewerLabels reference.

Customization

formatNumber follows locale, including non-Latin digits.

import { PdfViewer, type PdfViewerLabels } from '@kingtech/react-pdf-viewer'; // Label functions receive a formatter for the viewer's locale. const labels: Partial<PdfViewerLabels> = { zoomLevel: (percent, { formatNumber }) => `${formatNumber(percent)} %`, pageIndicator: (page, total, { formatNumber }) => `${formatNumber(page)} از ${formatNumber(total)}`, }; export default function Demo() { // Arabic-Indic digits from the "fa-IR" locale. return <PdfViewer source="/samples/multipage.pdf" locale="fa-IR" labels={labels} />; }

For translation workflows and right-to-left pages, see the Localization guide and the customization guide.

Advanced / escape hatch

PdfToolbar accepts the same labels and locale props for custom toolbars.

Limitations

Error messages are not labels. PdfViewerError.message is English. Workaround: map error.code to translated text in renderError.
No bundled translations. Only English ships with the package. Workaround: keep a labels object per language in your app’s translation files.
No right-to-left toolbar mirroring. The toolbar keeps its order in right-to-left pages. Workaround: build a mirrored toolbar with renderToolbar.

API

PdfViewerLabels — Every user-visible string and accessible name. Defaults are English; override any subset through the labels prop.
defaultLabels — The default English labels for every user-visible string and accessible name. Override any subset with the labels prop.
LabelContext — Helpers passed to label functions, such as locale-aware number formatting, so custom labels follow the viewer's locale.