国际化

界面语言

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

在插件模式中注册语言包

使用插件语言包是一件非常繁琐的事情，你需要从存在语言包的插件中引入对应的语言包，并将它们合并成一个对象传入 Univer 实例。以下是一个示例：

import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import DesignZhCN from '@univerjs/design/locale/zh-CN'import SheetsUIZhCN from '@univerjs/sheets-ui/locale/zh-CN'import UIZhCN from '@univerjs/ui/locale/zh-CN'const univer = new Univer({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      DesignZhCN,       UIZhCN,       SheetsUIZhCN,     ),  },})

在预设模式中注册语言包

预设包中已经包含了其对应插件的语言包，只需要从预设中引入即可。

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'const { univerAPI } = createUniver({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,     ),  },  presets: [    UniverSheetsCorePreset(),  ],})

合并语言包

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；需要两者同步变化时，请同时设置两项。

在 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 内容。

从右到左的布局

布局方向独立设置：初始化时使用 direction，或调用 univerAPI.setDirection('rtl') / setDirection('ltr')。仅修改 locale 或 region 不会切换布局方向。

univerAPI.setDirection('rtl')