Interface languages
Seven offline UI languages, locale negotiation, live updates and custom translations across File Viewer components.
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
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' } })<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
| 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
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.
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 and CLDR categories. 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
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.