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

**Demo: Hungarian labels**

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

> **Warning: Keep the labels object stable**
>
> Labels are merged once per object identity. An object literal written inline in JSX creates a new
>   object on every render. Define labels at module scope, or wrap them in `useMemo`.

### 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:

```tsx
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](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/pdf-viewer-labels/).

## Customization

`formatNumber` follows `locale`, including non-Latin digits.

**Demo: Persian digits with custom page and zoom labels**

```tsx
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](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/guides/localization/) and the [customization guide](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/customization/).

## Advanced / escape hatch

`PdfToolbar` accepts the same `labels` and `locale` props for [custom toolbars](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/custom-toolbar/).

## Limitations

- **Error messages are not labels.** `PdfViewerError.message` is English. Workaround: map `error.code` to translated text in [`renderError`](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/error-states/).
- **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`](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/custom-toolbar/).

## API

- [PdfViewerLabels](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/pdf-viewer-labels.md)
- [defaultLabels](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/default-labels.md)
- [LabelContext](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/label-context.md)

---

## PdfViewerLabels reference

Every user-visible string and accessible name. Defaults are English; override any subset
through the `labels` prop.

### Used by

- [Labels and locale](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/labels.md)

### Import

```ts
import type { PdfViewerLabels } from '@kingtech/react-pdf-viewer';
```

### Properties

| Name | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `viewer` | `string` | — | Yes | Accessible name of the viewer region. |
| `toolbar` | `string` | — | Yes | Accessible name of the toolbar. |
| `document` | `string` | — | Yes | Accessible name of the scrollable document area. |
| `zoomOut` | `string` | — | Yes | Button. |
| `zoomIn` | `string` | — | Yes | Button. |
| `zoomLevel` | `(percent: number, context: LabelContext) => string` | — | Yes | Zoom label text. |
| `resetZoom` | `string` | — | Yes | Reset-zoom button (with `zoomReset`) and menu item. |
| `previousPage` | `string` | — | Yes | Button. |
| `nextPage` | `string` | — | Yes | Button. |
| `pageIndicator` | `(page: number, total: number, context: LabelContext) => string` | — | Yes | Page label text. |
| `pageAriaLabel` | `(page: number, total: number, context: LabelContext) => string` | — | Yes | Accessible name of each page. |
| `pageInput` | `string` | — | Yes | Accessible name of the page-number input. |
| `enterFullscreen` | `string` | — | Yes | Fullscreen button outside fullscreen. |
| `exitFullscreen` | `string` | — | Yes | Fullscreen button in fullscreen. |
| `rotate` | `string` | — | Yes | Button. |
| `download` | `string` | — | Yes | Button. |
| `print` | `string` | — | Yes | Button. |
| `moreActions` | `string` | — | Yes | Overflow menu button shown when the toolbar is too narrow. |
| `loading` | `string` | — | Yes | Loading view text. |
| `retry` | `string` | — | Yes | Retry button of the error view. |
| `empty` | `string` | — | Yes | Announced when there is no document. |
| `printProgress` | `(done: number, total: number, context: LabelContext) => string` | — | Yes | Print preparation status. |
| `cancel` | `string` | — | Yes | Cancels print preparation. |
| `passwordPrompt` | `string` | — | Yes | Password form heading. |
| `passwordLabel` | `string` | — | Yes | Password field label. |
| `passwordSubmit` | `string` | — | Yes | Password submit button. |
| `passwordIncorrect` | `string` | — | Yes | Shown after a wrong password. |
| `thumbnails` | `string` | — | Yes | Accessible name of the thumbnails sidebar. |
| `search` | `string` | — | Yes | Accessible name of the search field. |
| `searchResults` | `(current: number, total: number, context: LabelContext) => string` | — | Yes | Search result status. |
| `searchPrevious` | `string` | — | Yes | Search button. |
| `searchNext` | `string` | — | Yes | Search button. |
| `searchNoResults` | `string` | — | Yes | Shown when nothing matches. |

### Source

[packages/react-pdf-viewer/src/labels.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/labels.ts#L13)


---

## defaultLabels reference

The default English labels for every user-visible string and accessible name. Override any subset with the `labels` prop.

### Used by

- [Labels and locale](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/labels.md)

### Import

```ts
import { defaultLabels } from '@kingtech/react-pdf-viewer';
```

Signature: `const defaultLabels: PdfViewerLabels`

### Properties

| Name | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `viewer` | `string` | `'PDF viewer'` | Yes | Accessible name of the viewer region. |
| `toolbar` | `string` | `'PDF controls'` | Yes | Accessible name of the toolbar. |
| `document` | `string` | `'Document'` | Yes | Accessible name of the scrollable document area. |
| `zoomOut` | `string` | `'Zoom out'` | Yes | Button. |
| `zoomIn` | `string` | `'Zoom in'` | Yes | Button. |
| `zoomLevel` | `(percent: number, context: LabelContext) => string` | `function` | Yes | Zoom label text. |
| `resetZoom` | `string` | `'Reset zoom'` | Yes | Reset-zoom button (with `zoomReset`) and menu item. |
| `previousPage` | `string` | `'Previous page'` | Yes | Button. |
| `nextPage` | `string` | `'Next page'` | Yes | Button. |
| `pageIndicator` | `(page: number, total: number, context: LabelContext) => string` | `function` | Yes | Page label text. |
| `pageAriaLabel` | `(page: number, total: number, context: LabelContext) => string` | `function` | Yes | Accessible name of each page. |
| `pageInput` | `string` | `'Page number'` | Yes | Accessible name of the page-number input. |
| `enterFullscreen` | `string` | `'Enter fullscreen'` | Yes | Fullscreen button outside fullscreen. |
| `exitFullscreen` | `string` | `'Exit fullscreen'` | Yes | Fullscreen button in fullscreen. |
| `rotate` | `string` | `'Rotate PDF'` | Yes | Button. |
| `download` | `string` | `'Download PDF'` | Yes | Button. |
| `print` | `string` | `'Print PDF'` | Yes | Button. |
| `moreActions` | `string` | `'More actions'` | Yes | Overflow menu button shown when the toolbar is too narrow. |
| `loading` | `string` | `'Loading PDF...'` | Yes | Loading view text. |
| `retry` | `string` | `'Retry'` | Yes | Retry button of the error view. |
| `empty` | `string` | `'No document'` | Yes | Announced when there is no document. |
| `printProgress` | `(done: number, total: number, context: LabelContext) => string` | `function` | Yes | Print preparation status. |
| `cancel` | `string` | `'Cancel'` | Yes | Cancels print preparation. |
| `passwordPrompt` | `string` | `'This document is password protected'` | Yes | Password form heading. |
| `passwordLabel` | `string` | `'Password'` | Yes | Password field label. |
| `passwordSubmit` | `string` | `'Open'` | Yes | Password submit button. |
| `passwordIncorrect` | `string` | `'Incorrect password. Please try again.'` | Yes | Shown after a wrong password. |
| `thumbnails` | `string` | `'Pages'` | Yes | Accessible name of the thumbnails sidebar. |
| `search` | `string` | `'Search in document'` | Yes | Accessible name of the search field. |
| `searchResults` | `(current: number, total: number, context: LabelContext) => string` | `function` | Yes | Search result status. |
| `searchPrevious` | `string` | `'Previous match'` | Yes | Search button. |
| `searchNext` | `string` | `'Next match'` | Yes | Search button. |
| `searchNoResults` | `string` | `'No matches'` | Yes | Shown when nothing matches. |

### Source

[packages/react-pdf-viewer/src/labels.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/labels.ts#L64)


---

## LabelContext reference

Helpers passed to label functions, such as locale-aware number formatting, so custom labels follow the viewer's `locale`.

### Used by

- [Labels and locale](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/labels.md)

### Import

```ts
import type { LabelContext } from '@kingtech/react-pdf-viewer';
```

### Properties

| Name | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `formatNumber` | `(value: number) => string` | — | Yes | Formats an integer for the viewer's `locale` (no grouping separators). |

### Source

[packages/react-pdf-viewer/src/labels.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/labels.ts#L4)