国际化
界面语言
locale 决定菜单、提示、对话框和其他界面文案使用哪套语言包,locales 只注册语言包,不指定当前语言。该设置对 Univer 实例中的所有文档单元生效。取值来自 LocaleType,例如 LocaleType.EN_US。
- 所有产品:界面:
locale切换菜单、提示、对话框和插件标签上的译文,不会翻译用户内容,也不会重命名已有文档单元。 - Sheets:单元格格式与公式:单元格中的数字和日期渲染时,先使用数字格式的 locale 覆盖值,再使用工作簿快照的
locale,最后使用实例的locale。region不会替代上述任何一项。DOLLAR等公式行为以及财务结果上的货币格式仍由locale决定,中日韩输入归一化同样使用locale。 - Docs:文档统计:
locale决定分词和字数统计。
运行时切换语言
切换语言之前,应加载所有已安装插件或预设的语言包。loadLocales() 只合并翻译,不切换语言;setLocale() 只选择已加载的语言包,不会下载任何内容。缺失的翻译键会直接显示为键名。下面的示例只加载共享 UI 语言包;其他已安装插件的目标语言包应在同一次调用中一并合并。
import { LocaleType, mergeLocales } from '@univerjs/core'import UIEnUS from '@univerjs/ui/locale/en-US'univerAPI.loadLocales(LocaleType.EN_US, mergeLocales(UIEnUS))univerAPI.setLocale(LocaleType.EN_US)console.log(univerAPI.getCurrentLocale()) // enUS合并语言包
mergeLocales 将多个插件或预设的语言包合并为一个完整的语言包对象。下面两种写法均可使用:
import { mergeLocales } from '@univerjs/core'// 你可以传入多个语言包对象进行合并const locales = mergeLocales( plugin1Locales, plugin2Locales, presetLocales,)// 也可以传入一个语言包对象数组const locales = mergeLocales([ plugin1Locales, plugin2Locales, presetLocales,])import { mergeLocales } from '@univerjs/presets'// 你可以传入多个语言包对象进行合并const locales = mergeLocales( plugin1Locales, plugin2Locales, presetLocales,)// 也可以传入一个语言包对象数组const locales = mergeLocales([ plugin1Locales, plugin2Locales, presetLocales,])自定义语言包
Univer 也支持自定义语言包。按需构造语言包对象并传给 Univer 实例。预设语言包通常位于 <rootDir>/packages/<PLUGIN_NAME>/locale 目录下。
import { LocaleType, Univer } from '@univerjs/core'const univer = new Univer({ locale: LocaleType.JA_JP, locales: { [LocaleType.JA_JP]: { ui: { shortcut: { undo: '元に戻す', redo: 'やり直す', }, }, }, },})贡献语言包
Univer 目前内置以下语言包:
zh-CN:简体中文en-US:英文zh-TW:繁体中文zh-HK:繁体中文(香港)ru-RU:俄文vi-VN:越南文fa-IR:波斯文fr-FR:法文ja-JP:日文ko-KR:韩文es-ES:西班牙文ca-ES:加泰罗尼亚文sk-SK:斯洛伐克文ar-SA:阿拉伯文de-DE:德文id-ID:印尼文it-IT:意大利文pl-PL:波兰文pt-BR:葡萄牙文(巴西)
Univer 是开源项目,欢迎各地开发者补充或改进语言包。
地区设置
region 决定需要地区习惯的功能使用哪套地区规则。该设置同样对 Univer 实例中的所有文档单元生效。
两项设置都使用 LocaleType 值。例如 LocaleType.EN_US 对应的值是 enUS,而 en-US 既是语言包文件名,也是 BCP 47 标签。不要将 US、SG 等国家代码传给 region。界面使用其他语言时,地区不需要对应的语言包。
如果从未设置 region,它会跟随 locale,后续调用 setLocale() 时也会随之变化。在初始化时设置 region 或调用 setRegion() 后,不再自动跟随,之后切换语言会保留已选定的地区。目前没有恢复自动跟随的公开 API,两者需要一起变更时应同时调用两个 setter。
在 createUniver() 或 new Univer() 中为 locale 添加 region: LocaleType.DE_DE,即可保留界面语言并使用德国地区习惯。
import { LocaleType } from '@univerjs/core'univerAPI.setRegion(LocaleType.DE_DE)univerAPI.setLocale(LocaleType.EN_US)console.log(univerAPI.getCurrentRegion()) // deDE此时界面为英文,地区格式仍按德国习惯处理。getCurrentLocale() 和 getCurrentRegion() 返回实际生效的标识。要让两者一起变更,使用同一个 LocaleType 值分别调用两个 setter。
- Sheets:货币操作:
region决定货币工具栏图标、货币和会计格式的选项及预览,以及货币命令应用的格式。更改该设置不会重写已有单元格格式,也不会换算金额。 - Docs:文档统计:
region决定统计对话框和状态栏中数字的显示格式,例如分组分隔符。仅更改region不会改变统计规则。 - 启用评论时:
region决定日期时间的显示格式,采用 24 小时制和拉丁数字;locale决定评论界面文案。两者都不会修改已存储的时间戳,region也不是时区设置。 - Boards、Slides、Bases、PDFs:
locale控制界面翻译。region供读取它的共享功能使用,例如集成后的评论;它不会自动重新格式化白板或幻灯片文本、Base 字段或 PDF 内容。
从右到左的布局
注意
目前 RTL 仅支持 UI 层,渲染层不支持 RTL。
注意事项
并非所有插件都包含语言包。各功能文档会说明哪些插件提供语言包。
univerAPI.setDirection('rtl')你觉得这篇文档如何?