# 界面国际化 (/zh/guide/i18n)

[English](/guide/i18n)

core 同步内置 `zh-CN`、`en-US`、`ja-JP`、`zh-TW`、`zh-HK`、`de-DE`、`ru-RU`，翻译资源无需联网。Vanilla、Web Component、Vue 3、Vue 2.6/2.7、React、React Legacy、Svelte、jQuery 的轻量包和 full 包共用资源。官网和开发文档保持中英路由。

## Vanilla / Web Component 接入 [#vanilla--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' }
})
// 选择器使用注册表中的 value 和语言本名 label。
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>
```

Web Component 可更新 `element.locale` 或通过 `element.options` 传入语言。其他框架更新现有的 `options` prop；Svelte action 使用 `action.update`，jQuery 使用 `.fileViewer('update', { options: { locale } })`。语言切换保留当前文件、页码、缩放、滚动、搜索条件和工作表，不重新下载或解析文件。格式配置发生变化时，仍按原有规则重新渲染。

## 语言匹配与隔离 [#语言匹配与隔离]

| 输入 | 使用字典 |
| --- | --- |
| `zh`、`zh-CN`、`zh-SG`、`zh-Hans-*` | `zh-CN` |
| `zh-TW`、`zh-Hant`、非港澳的其他 `zh-Hant-*` | `zh-TW` |
| `zh-HK`、`zh-MO`、`zh-Hant-HK`、`zh-Hant-MO` | `zh-HK` |
| 英语、日语、德语、俄语的地区变体 | 对应内置语言 |

显式脚本优先：`zh-Hans-HK` 使用简体，`zh-Hant-CN` 使用台湾繁体。支持大小写和下划线。非法或不支持的显式标签回退英语，不向界面抛出标签异常。

`auto` 依次检查 `navigator.languages`，再检查 `navigator.language`；浏览器偏好均不受支持时回退英语，没有浏览器信息时保留原有简体默认。浏览器语言变化只影响自动实例。SSR 应明确指定语言，保持服务端与客户端一致。

每个预览器独立维护语言上下文。压缩包条目、邮件附件等嵌套预览默认继承父实例。组件不读写宿主语言偏好存储，不修改宿主页面语言；文档自身的语言、方向、字体、文件名和原始元数据保持原意。Demo 使用“URL 参数 → 已保存选择 → 浏览器偏好”的优先级，容忍存储不可用，并保留当前文件。

## 自定义文案与渲染器 [#自定义文案与渲染器]

`options.i18n.locale`、`options.i18n.messages` 优先于顶层字段。现有消息键保持稳定，字符串字典和消息回调均可覆盖官方资源，回调返回 `undefined` 时使用内置文案。保留 `{param}` 插值；自定义回调收到原始数字，并自行决定格式。

```ts
const options = {
  locale: 'zh-TW',
  i18n: { messages: { 'toolbar.download': '下載原始檔案' } }
}
```

自定义渲染器可使用可选的 `FileRenderContext.i18n` 进行翻译、数量/日期/文件大小格式化和变更订阅。推荐 `createFileViewerTranslator(context.i18n || context.options)`，兼容独立 IIFE 渲染器。通过 `t.text`、`t.attr`、`t.bind` 显式绑定界面文案，不扫描或匹配文档正文来替换文本；渲染器销毁时清理订阅。

永久替换已绑定的界面子树（例如重建导航列表）前，调用 `t.release(root)` 释放该子树的订阅，语言上下文继续有效，同一节点随后仍可重新绑定。待复用的缓存节点保留其绑定；渲染器作用域销毁时释放其余订阅。

计数按原始数字使用 [`Intl.PluralRules`](https://tc39.es/ecma402/#sec-intl-pluralrules-objects) 与 [CLDR 分类](https://cldr.unicode.org/index/cldr-spec/plural-rules)。缺少 Intl 能力时使用随包降级规则。文件大小采用明确的二进制单位 `B/KiB/MiB/GiB/TiB`；无法按地区格式化日期时使用无歧义的 ISO 表示。

## 边界与审校 [#边界与审校]

浏览器原生打印对话框、文件选择窗口和原生媒体控件由浏览器或操作系统管理。第三方文档内容和原始解析诊断保留诊断价值；翻译不改变签名有效性、格式支持程度和授权含义。运行资源继续自托管。

本轮新增及调整的翻译已纳入技术覆盖和术语检查，七种语言的独立母语审校仍待完成，源码中的 `docs/maintenance/i18n-review.md` 单独记录其范围。`pnpm test:i18n` 验证资源、占位符、解析、实例隔离和复数；构建受影响的包后运行 `node test/i18n.browser.mjs` 验证各框架原生组件。新增语言扩展注册表和资源，沿用同一套门禁。
