国际化

界面语言

locale 决定菜单、提示、对话框和其他界面文案使用哪套语言包,locales 只注册语言包,不指定当前语言。该设置对 Univer 实例中的所有文档单元生效。取值来自 LocaleType,例如 LocaleType.EN_US。

  • 所有产品:界面:locale 切换菜单、提示、对话框和插件标签上的译文,不会翻译用户内容,也不会重命名已有文档单元。
  • Sheets:单元格格式与公式:单元格中的数字和日期渲染时,先使用数字格式的 locale 覆盖值,再使用工作簿快照的 locale,最后使用实例的 locale。region 不会替代上述任何一项。DOLLAR 等公式行为以及财务结果上的货币格式仍由 locale 决定,中日韩输入归一化同样使用 locale。
  • Docs:文档统计:locale 决定分词和字数统计。

运行时切换语言

切换语言之前,应加载所有已安装插件或预设的语言包。loadLocales() 只合并翻译,不切换语言;setLocale() 只选择已加载的语言包,不会下载任何内容。缺失的翻译键会直接显示为键名。下面的示例只加载共享 UI 语言包;其他已安装插件的目标语言包应在同一次调用中一并合并。

TypeScript
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 将多个插件或预设的语言包合并为一个完整的语言包对象。下面两种写法均可使用:

TypeScript
import { mergeLocales } from '@univerjs/core'// 你可以传入多个语言包对象进行合并const locales = mergeLocales(  plugin1Locales,  plugin2Locales,  presetLocales,)// 也可以传入一个语言包对象数组const locales = mergeLocales([  plugin1Locales,  plugin2Locales,  presetLocales,])

自定义语言包

Univer 也支持自定义语言包。按需构造语言包对象并传给 Univer 实例。预设语言包通常位于 <rootDir>/packages/<PLUGIN_NAME>/locale 目录下。

TypeScript
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,即可保留界面语言并使用德国地区习惯。

TypeScript
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。

注意事项

并非所有插件都包含语言包。各功能文档会说明哪些插件提供语言包。

TypeScript
univerAPI.setDirection('rtl')

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.