# Interface languages (/guide/i18n)

[简体中文](/zh/guide/i18n)

The shared core bundles `zh-CN`, `en-US`, `ja-JP`, `zh-TW`, `zh-HK`, `de-DE` and `ru-RU` synchronously. UI translations need no network request. Vanilla, Web Component, Vue 3, Vue 2.6/2.7, React, React Legacy, Svelte and jQuery use the same resources in light and Full packages. Documentation and the website retain English and Simplified Chinese routes.

## Start with Vanilla or Web Component [#start-with-vanilla-or-web-component]

```ts
import { mountViewer } from '@file-viewer/web-full'
import { FILE_VIEWER_LOCALE_OPTIONS } from '@file-viewer/core'

const viewer = mountViewer(document.getElementById('preview')!, {
  url: '/files/report.pdf',
  options: { locale: 'zh-TW' }
})
// Use each option's value and native label in your language selector.
console.table(FILE_VIEWER_LOCALE_OPTIONS)
await viewer.update({ options: { locale: 'ru-RU' } })
```

```html
<flyfish-file-viewer src="/files/report.pdf" locale="ja-JP"></flyfish-file-viewer>
```

Set `element.locale` or `element.options.locale` through the existing element API. Framework components update their `options` prop; Svelte actions use `action.update`, and jQuery uses `.fileViewer('update', { options: { locale } })`. The current document, page, zoom, scroll, search and worksheet remain in place. A language update does not download or parse the source again. Renderer configuration changes still follow their usual reload rules.

## Negotiation and isolation [#negotiation-and-isolation]

| Input | Dictionary |
| --- | --- |
| `zh`, `zh-CN`, `zh-SG`, `zh-Hans-*` | `zh-CN` |
| `zh-TW`, `zh-Hant`, other non-HK/MO `zh-Hant-*` | `zh-TW` |
| `zh-HK`, `zh-MO`, `zh-Hant-HK`, `zh-Hant-MO` | `zh-HK` |
| English, Japanese, German or Russian regional variants | Matching bundled language |

Explicit script wins: `zh-Hans-HK` uses Simplified Chinese and `zh-Hant-CN` uses Taiwan Traditional Chinese. Case and underscores are accepted. Invalid or unsupported explicit tags fall back to English.

`auto` checks `navigator.languages` in order, then `navigator.language`; unsupported browser preferences fall back to English. With no browser information, the historical Simplified Chinese default remains. Browser `languagechange` events affect automatic instances only. Use an explicit locale for matching SSR and hydration output.

Each instance owns its language context. Nested archive entries and mail attachments inherit it. Components do not access host preference storage or change the host document's language. Authored content, its language/direction/fonts, filenames and raw metadata retain their original meaning. Demo preferences use URL → saved choice → browser priority, tolerate unavailable storage and preserve the selected file.

## Override copy and extend renderers [#override-copy-and-extend-renderers]

`options.i18n.locale` and `options.i18n.messages` take priority over their top-level counterparts. Message keys are stable. A string dictionary or callback can override any official message; returning `undefined` uses built-in copy. `{param}` interpolation remains supported. Callbacks receive original numeric values and own their formatting.

```ts
const options = {
  locale: 'de-DE',
  i18n: { messages: { 'toolbar.download': 'Datei speichern' } }
}
```

Custom renderers can use the optional `FileRenderContext.i18n` for translation, number/date/byte formatting and change subscriptions. Prefer `createFileViewerTranslator(context.i18n || context.options)` so subscriptions also work in separately bundled IIFE renderers. `t.text`, `t.attr` and `t.bind` mark UI explicitly; never translate document content by matching DOM strings. Dispose subscriptions when the renderer is destroyed.

Call `t.release(root)` before permanently replacing a bound UI subtree, such as a rebuilt navigation list. It releases that subtree's subscriptions while leaving the language context active; the same nodes can be bound again later. Keep bindings on cached nodes that will be reused. Renderer-scope destruction releases the remaining subscriptions.

Counts use raw numbers with [`Intl.PluralRules`](https://tc39.es/ecma402/#sec-intl-pluralrules-objects) and [CLDR categories](https://cldr.unicode.org/index/cldr-spec/plural-rules). Offline fallback rules cover missing Intl support. File sizes use explicit binary units (`B`, `KiB`, `MiB`, `GiB`, `TiB`). When localized date formatting is unavailable, dates fall back to unambiguous ISO strings.

## Boundaries and translation review [#boundaries-and-translation-review]

Browser print dialogs, file pickers and native media controls follow the browser or operating system language. Third-party document content and original parser diagnostics remain available for diagnosis; UI translation does not change signature validity, support level or licensing. Runtime resources must remain self-hosted.

The new and revised translations have technical coverage checks and terminology review. Independent native-speaker review is pending for all seven languages and is tracked in the source inventory `docs/maintenance/i18n-review.md`. Run `pnpm test:i18n` for dictionary, interpolation, negotiation, isolation and plural checks, and `node test/i18n.browser.mjs` after building the affected packages for native framework runtime checks. New languages extend the registry and resources and use the same gates.
