界面国际化
File Viewer 七语言离线界面、语言匹配、运行时切换、自定义文案及跨框架接入。
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 接入
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' } })<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} 插值;自定义回调收到原始数字,并自行决定格式。
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 与 CLDR 分类。缺少 Intl 能力时使用随包降级规则。文件大小采用明确的二进制单位 B/KiB/MiB/GiB/TiB;无法按地区格式化日期时使用无歧义的 ISO 表示。
边界与审校
浏览器原生打印对话框、文件选择窗口和原生媒体控件由浏览器或操作系统管理。第三方文档内容和原始解析诊断保留诊断价值;翻译不改变签名有效性、格式支持程度和授权含义。运行资源继续自托管。
本轮新增及调整的翻译已纳入技术覆盖和术语检查,七种语言的独立母语审校仍待完成,源码中的 docs/maintenance/i18n-review.md 单独记录其范围。pnpm test:i18n 验证资源、占位符、解析、实例隔离和复数;构建受影响的包后运行 node test/i18n.browser.mjs 验证各框架原生组件。新增语言扩展注册表和资源,沿用同一套门禁。