11.md · Adair520/odoo-cookbook

# 第十一章 国际化

全书完整目录请见：[Odoo 14开发者指南（Cookbook）第四版](README.md)

Odoo支持多语言并允许不同的用户根据自己的方便选用不同的语言。这通过Odoo内置的i18n功能实现。通过字符串翻译，Odoo还支持日期的数字格式及时间格式化等。

本章中，我们将学习如何在Odoo中启用多语言以及如何在自定义模块中添加翻译文件。在掌握这些新功能时会有助于提升Odoo的用户体验。

本章中，我们将讲解如下内容：

- 安装语言及配置用户首选项
- 配置语言相关设置
- 通过网页客户端在用户界面翻译文本
- 将翻译字符串导出到文件
- 使用`gettext`工具来简化翻译
- 将翻译文件导入到Odoo中
- 对网站修改自定义URL语言代码

这里的很多操作可以通过网页客户端用户界面或命令行来完成。在可以使用的地方，我们会讲解两种选项的使用方法。

## 安装语言及配置用户首选项

Odoo已预置了本地化，也就是说它支持多语言和本地化设置，如日期和数字格式。

初次安装时，仅能使用默认语言英语。要对用户开放其它语言和地点，需要先安装这些语言。本节中，我们将学习如何设置用户首选项以及如何进行应用。

### 如何实现...

启用开发者模式并按照如下步骤在Odoo实例中安装新的语言：

1. 访问Settings > Translations > Load a Translation菜单项。这里有如下图所示的Add Language链接。点击该链接会打开一个加载语言的对话框：
   ![图11.1 – 通用设置中的语言选项](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021030809040060.png)
   图11.1 – 通用设置中的语言选项

2. 选择想要加载的语言：
   ![图11.2 – 加载语言的对话框](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021030809071950.png)
   图11.2 – 加载语言的对话框

3. 点击Add按钮会加载所选中的语言，会打开如下所示的确认对话框：
   ![图11.3 – 显示语言加载的对话框](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021030809102084.png)
   图11.3 – 显示语言加载的对话框

4. 新语言也可以通过命令行来安装。与上一步同等的命令如下：

```
   $ ./odoo-bin -d mydb --load-language=zh_CN
   ```

5. 要设置用户使用的语言，访问Settings > Users & Companies > Users，在用户表单的首选项（Preferences）标签中设置语言（Language）字段的值。在同一界面还可以设置用户的时区：
   ![图11.4 – 设置语言的用户表单](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021030809180197.png)
   图11.4 – 设置语言的用户表单

用户也可以通过Preferences菜单项来进行这些配置。点击网页端窗口右上角的用户名即可。

### 运行原理...

用户可以有自己的语言和时区首选项。语言设置用于将用户界面的文本翻译为所选的语言并按本地习惯应用浮点和货币字段。

在语言可供用户选择之前，它必须通过**Add language**选项进行过安装。可用的语言列表在开发者模式下可通过Settings > Translations > Languages菜单项进行查看。带有active标记的语言是已安装的。

每个Odoo插件模块负责其自身的翻译资源，位于i18n子目录中。每种语言的数据应放在 .po文件中。在我们的示例中，西班牙语的翻译文件通过es_ES.po（中文zh_CN.po）数据文件进行加载。

Odoo还支持基本语言（base language）的概念。例如，如有西班牙语的es.po文件和墨西哥西班牙语的es_MX.po 文件，那么es.po会作为es_MX.po的基本语言。在安装西语的时候，两个数据文件都会被加载，先安装基本语言，再安装指定的语言。因此，具体语言的翻译文件仅需包含针对语言变体部分的字符串，在本例中即为墨西哥西班牙语。

`i18n`子目录中还应包含 `<module_name>.pot`文件，提供一个翻译的模板并包含所有的可翻译字符串。本章中*将翻译字符串导出到文件*一节讲解了如何导出可翻译字符串生成该文件。

在安装一种语言时，对应的资源从所有已安装的插件模块中载入并在Translated Terms模型中保存。它的数据可以在 Settings > Translations > Application Terms > Translated Terms 菜单项（注意仅在开发者模式下可见）中进行查看（和编辑）。

已安装语言的翻译文件还会在新插件模块安装或已有插件模块升级时进行载入。

### 扩展知识...

通过再次点击语言中的刷新图标即可在无需升级插件模块的情况下重新载入翻译文件。如果升级了翻译文件而又不想经历升级模块（及其所有依赖）的麻烦时可以使用这种方法。

如未勾选 Overwrite Existing Terms复选框，仅加载新翻译的字符串。因此，修改的已翻译字符串不会被加载。如果你希望已存在的翻译也被加载则勾选复选框，这样会覆盖当前已加载的翻译。注意这样在有人通过用户界面手动修改翻译时可能会导致潜在问题。

存在前面的复选框是因为我们可以通过进入Settings > Translations > Application Terms > Translated Terms菜单项或在调试菜单中使用Technical Translation快捷选项来编辑指定的翻译。以这种方式添加或修改的翻译不会被覆盖，除在重新加载语言时勾选了Overwrite Existing Terms。

同时插件模块可以在i18n_extra子文件夹中带有额外的翻译文件。首先， 下载了i18n子目录中的 .po文件。然后Odoo ORM对基本语言下载文件，然后对变种语言进行下载。按照这个顺序，下载i18n_extra子目录中的.po文件，首先会下载基础语言，然后下载语言变种。最后加载的字符串翻译即为当前使用的。

## 配置语言相关设置

语言和它们的变种（如`es_MX`为墨西哥西班牙语）也提供本地化设置，如日期和数字格式。

它们都有相应的默认值，只要用户使用正确的语言，本地化设置就应该是正确的。

但是你可能会想要修改语言的设置。比如，你可能会偏向于在用户界面中使用默认的英语，但又希望修改美式英语的默认日期和数字格式匹配自己的要求。

### 准备工作

我们需要启用开发者模式。如未启用请参照[第一章 安装Odoo开发环境](1.md)*激活Odoo开发者工具*一节进行激活。

### 如何实现...

按照如下步骤来修改语言的本地化设置：

1. 选择Settings > Translations > Languages菜单项来检查所安装的语言和它们的设置。点击所安装的一种语言会打开带有相应设置的表单：
   ![图11.5 – 配置语言设置的表单](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021031314133831.png)
   图11.5 – 配置语言设置的表单
2. 编辑语言设置。修改日期为ISO格式，将日期格式修改为%Y-%m-%d.。要修改数字格式来使用逗号作为十进制分隔符，修改对应的十进制分隔符和千分位分隔符。

### 运行原理...

在登录并创建新的Odoo用户会话时，用户首选项中勾选了用户语言并在`lang`上下文键中进行了设置。然后使用它来格式化对应的输出 - 源文本翻译为用户语言，日期和数字以语言的当前本地化设置进行格式化。

### 扩展知识...

服务端进程可修改动作所运行的上下文。例如，要获取根据美式英语格式设置了日期格式的记录集，不依赖当前用户的语言首选项，可以进行如下操作：

```
en_records = self.with_context(lang='en_US').search([])
```

更多详情，请参见[第八章 高级服务端开发技巧](8.md)中的*使用变更的上下文调用方法*一节。

## 通过网页客户端在用户界面翻译文本

进行翻译最简单的方式是使用由网页客户端提供的翻译功能。这些翻译字符串在数据库中存储，稍后可导出为`.po`文件，要么在插件模块中包含，要么之后进行手动导入。

文本字段可带有可翻译内容，也就是说它们的值可以依赖于当前用户的语言。我们还将学习如何在这些字段中设置依赖于语言的值。

### 准备工作

我们需要启用开发者模式。如未启用请参照[第一章 安装Odoo开发环境](1.md)中*激活Odoo开发者工具*一节进行激活。

### 如何实现...

我们使用用户组作为示例来演示如何通过网页客户端翻译词汇：

1. 导航至想要进行翻译的页面。本例我们通过Settings > Users & Companies > Groups菜单项打开用户组的视图。
2. 在顶部菜单栏中，点击调试菜单图标并选择Technical Translation选项：
   ![图11.6 – 在当前视频中打开翻译选项](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021031314285569.png)
   图11.6 – 在当前视频中打开翻译选项
3. 会显示针对该视图的可翻译词语的列表。编辑某行的Translation Value来修改（或添加）其翻译文本。如果要查找某个具体的源字符串，可使用所列出的过滤器来精简出所显示的文本：
   ![图11.7 – 视图的翻译词语](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021031314350797.png)
   图11.7 – 视图的翻译词语
   组名是可翻译字段。我们来将记录值翻译为所安装的其它语言。
4. 再次导航至User Groups菜单项，在表单视图中打开其中一条组记录，并点击Edit：
   ![图11.8 – 字段值的翻译](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021031314403966.png)
   图11.8 – 字段值的翻译
5.  注意在Name字段的最右端有一个特殊的图标。这表示它是一个可翻译字段。点击该图标打开带有各个安装语言的翻译列表。这样我们可以对这些语言设置翻译。

### 运行原理...

在ir.translation模型的数据表中进行存储。调试菜单下的Technical Translation选项包含对这些词汇的快速访问，与当前所选择的视图保持对应。

类似地，带有可翻译内容的模型字段可包含一个访问已安装语言列表的图标并为每种语言设置相应的值。

此外，可以使用Translations > Application Terms > Translated Terms菜单项来从Settings顶部菜单访问翻译词汇。这里，可以看到所有针对我们实例的可用词汇。应使用数据过滤器来定位想要找到的词汇。

### 扩展知识...

Translated Terms菜单项的旁边可以看到一个Generate Missing Term选项。选择它会显示一个对话窗口，包含所安装的语言，然后会从已安装的插件模块中提取可翻译字符串，将新增的词句添加到Translated Terms表格中。与本章*将翻译字符串导出到文件*一节异曲同工。

在修改一些模型或视图后这会非常实用。这么做会添加新字符串，这样我们就可以对它们进行翻译。

它也可用于从默认en_US语言中获取字符串。然后我们可以利用翻译词句来替换原始英语文本为更适合终端用户具体业务的词汇。

> 📝重要：在主网站语言外的语言中编辑QWeb视图时，会发现只能修改字符串。这是因为在其它语言中，实际上只能通过Odoo的国际化机制向节点的文本内容添加翻译。

## 将翻译字符串导出到文件

可导出带有或不带有翻译文本所选语言。可在模块中包含i18n数据，或者稍后通过文本编辑器或是专业工具来执行翻译。

我们将演示如何使用标准mail模块来进行导出，读者可以修改为自己想要进行导出的模块。

### 准备工作

我们需要启用开发者模式。如未启用请参照[第一章 安装Odoo开发环境](1.md)中*激活Odoo开发者工具*一节进行激活。

### 如何实现...

按照如下步骤来导出mail插件模块的翻译词句：

1. 在网页客户端用户界面的Settings顶级菜单中选择Translations > Import/Export > Export Translation菜单项。

2. 在Export Translations对话框中，选择所要导出翻译的语言、文件格式以及要导出的模块。要导出翻译模板文件，从Language下拉列表中选择New Language (Empty translation template)。推荐使用 .po格式并且一次只导出一个插件模块 - 本例中为Discuss模块（mail是Discuss应用的技术名称）：
   ![图11.9 – 导出翻译词句对话框](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021042514035815.png)图11.9 – 导出翻译词句对话框

3. 完成导出后，会显示一个新的窗口，包含一个下载文件的链接以及一些建议。

4. 通过Odoo命令行界面导出mail插件模块的翻译模板文件，键入如下命令：

```
   $ ./odoo-bin -d mydb --i18n-export=mail.po --modules=mail
   $ mv mail.po ./addons/mail/i18n/mail.pot
   ```

5. 若要通过Odoo命令行界面导出某种语言的翻译模板文件 - 本例中为针对西语的es_ES，键入如下命令：

```
   $ ./odoo-bin -d mydb --i18n-export=es_ES.po --modules=mail --language=es_ES
   $ mv es_ES.po ./addons/mail/i18n
   ```

### 运行原理...

Export Translation功能完成两件事：从目标模块导出可翻译字符串，在ir.translation模型中添加新字符串，然后通过翻译词句创建一个文件。可通过网页客户端和命令行界面来进行实现。

在通过网页导出时，我们可以选择导出空翻译模板，即带有待翻译字符串和空白翻译的文件，或选择导出一种语言，文件中包含待翻译字符串，及所选语言的翻译内容。

可以选择的文件格式有CSV, PO和TGZ。TGZ文件格式导出一个包含PO或POT文件的<name>/i18n/目录结构的压缩文件。

CSV格式可用于通过Excel执行翻译，但在插件模块中所使用的格式是PO文件。它们应放在i18n子目录中。然后在相应的语言安装时自动加载。在导出这些PO文件时，我们应一次仅导出一个模块。PO文件也是一些翻译工具如Poedit所支持的流行格式。

翻译还可以直接通过命令行使用--i18nexport选项进行导出。本节展示如何导出模板文件和已翻译语言文件。

本节的第4步中，我们导出了一个模板文件。--i18n-export 选项需要传入导出路径和文件名。记住文件的扩展名要求为CSV, PO或TGZ。该选项需要一个-d参数，用于指定所使用的数据库。还需要--modules选项来指定要导出的插件模块。注意这里无需使用--stop-after-init选项，因为导出命令在完成后自动返回命令行。

这会导出一个模板文件。Odoo模块导出的模板应放在i18n文件夹中，扩展名为 .pot。在对模块完成导出操作后，我们通常会将导出的PO文件移到模块的i18n目录中，使用名称<module>.pot。

在第5步中，还使用到了--language选项。通过它，导出的不是空翻译文件，而是所选语言的已翻译词句。一种情况是使用Technical Translation功能来通过网页客户端用户界面来执行一些翻译，然后将它们一并导出至模块中。

### 扩展知识...

视图和模型定义中的文本字符串会自动提取供翻译。对于模型，会提取_description属性、字段名（string属性）、帮助文本和选择字段选项以及模型约束（_constraints和_sql_constraints）的用户文本。

Python或JavaScript代码中需翻译的文本字符串不会进行自动检查，因此代码应标识出这些字符串，通过下划线函数内封装这些字符串。

在模块的Python文件中，应确保使用如下语句进行导入：

```
from odoo import _
```

然后它在用到要翻译的文本时可以这样使用：

```
_('Hello World')
```

对于那些要使用上下文信息的字符串，我们应使用Python的字符串内插，如下所示：

```
_('Hello %s') % 'World'
```

注意插值应放在翻译函数的外面。例如，_("Hello %s" % 'World')是错误的。字符串插值最好应为字符串拼接，这样每个界面文本也仅是一个翻译字符串。

对Selection字段要保持警惕！如果对字段定义传递了明确的值列表，显示的字符串会自动标记为翻译。而如果传递一个返回值列表的方法，显示字符串必须显式地标记供翻译。

对于手动翻译工作，可以使用任何文本编辑器，但使用特别支持PO文件语法的编辑器会减少格式上的错误，让任务变得轻松。这类编辑器如下所示：

- [POEDIT](https://poedit.net/)
- [Emacs (PO模式)](https://www.gnu.org/software/gettext/manual/html_node/PO-Mode.html):
- [Lokalize](http://i18n.kde.org/tools)
- [Gtranslator](https://wiki.gnome.org/Apps/Gtranslator):

## 使用gettext工具来简化翻译

PO文件格式是gettext国际化和本地化系统的一部分，它在类Unix系统中经常使用。该系统包含简化翻译任务的一些工具。

本节演示如何使用这些工具来辅助翻译插件模块。我们要对自定义模块使用它，所以[第三章 创建Odoo插件模块](3.md)中创建的my_library是一个不错的对象。但是，请随意替换为你自己手边的其它自定义模块，将本节中的my_library替换为相应模块即可。

### 如何实现...

要通过命令行来管理翻译，假定Odoo的安装位置为~/odoo-work/odoo，执行如下步骤：

1. 创建一个目标语言如西语翻译词语的汇总。如果我们的汇总文件名为odoo_es.po，应编写如下代码：

```
   $ cd ~/odoo-work/odoo # 使用你Odoo安装的路径 
   $ find ./ -name es_ES.po | xargs msgcat --use-first | msgattrib -- translated --no-fuzzy -o ./odoo_es.po
   ```

2. 通过Odoo命令行界面导出该插件模块的翻译模板文件并将其放在模块中相应位置：

```
   $ ./odoo-bin -d mydb --i18n-export=my_module.po --modules=my_module
   $ mv my_module.po ./addons/my_module/i18n/my_module.pot
   ```

3. 如果针对目标语言还没有翻译文件，创建一个PO翻译文件，复用我们在汇总中已发现和翻译的词语：

```
   $ msgmerge --compendium ./odoo_es.po -o ./addons/my_module/i18n/es_ES.po \
    /dev/null ./addons/my_module/i18n/my_module.pot
   ```

4. 如果翻译文件存在，在汇总中添加翻译：

```
   $ mv ./addons/my_module/i18n/es_ES.po /tmp/my_module_es_old.po
   $ msgmerge --compendium ./odoo_es.po -o ./addons/my_module/i18n/es_ES.po \
   /tmp/my_module_es_old.po ./addons/my_module/i18n/my_module.pot
   $ rm /tmp/my_module_es_old.po
   ```

5. 使用如下命令查看PO文件中未翻译的词语：

```
   $ msgattrib --untranslated ./addons/my_module/i18n/es_ES.po
   ```

6. 使用你喜欢的编辑器完成翻译。

### 运行原理...

第1步使用gettext工具中的命令来创建所选择语言的翻译汇总（Compendium） - 本例中为西语。通过在Odoo代码中查找所有的es_ES.po文件并将其传递给msgcat命令来进行实现。我们使用 --use-first标记来避免翻译的冲突（在Odoo代码中已存在一些翻译）。结果会传递给msgattrib过滤器。我们使用--translated选项来过滤掉未翻译的词条，使用--no-fuzzy选项来移除模糊翻译。然后我们将结果保存到odoo_es.po中。

前一部分的第2步使用--i18n-export选项调用odoo.py。我们需要对命令行指定数据库，虽然在配置文件中已指定过数据库，还有--modules选项，接一个要导出翻译的以逗号分隔的模块列表。

在gettext的世界中，模糊翻译是对源字符串通过msgmerge命令（或其它工具）使用邻近匹配所自动创建的。我们需要在汇总中避免使用。

第3步通过在汇总中查找到的已有翻译值新建一个翻译文件。msgmerge命令配合--compendium使用来在汇总文件中查找msgid，匹配那些在第2步中生成的翻译模板文件中的内容。结果保存在es_ES.po 文件中。

如果插件已有包含希望持久化翻译的.po文件，应对其重命名并将 /dev/null参数替换为该文件。需要有重命名这一步，以避免在输入和输出中使用相同的文件。

### 扩展知识...

本小节只涉及到GNU gettext工具集中丰富工具的冰山一角。完整的讲解不是本书的范畴。如果读者兴趣，GNU gettext的文档包含大量的有关对PO操作的信息，参见http://www.gnu.org/software/gettext/manual/gettext.html。

## 将翻译文件导入到Odoo中

加载翻译的常用做法是把PO文件放在模块的i18n子目录内。在插件模块安装或升级时，会加载翻译文件并添加新翻译的字符串。

但是，有些情况下我们希望直接导入翻译文件。本节中我们会学习如何加载翻译文件，既可以通过网页客户端也可以通过命令行。

### 准备工作

我们需要启用开发者模式。如未启用请参照[第一章 安装Odoo开发环境](1.md)中*激活Odoo开发者工具*一节进行激活。我们还会需要一个po翻译文件，例如myfile.po文件，在本节中我们将进行导入操作。

### 如何实现...

按照如下步骤来导入翻译词句：

1. 在网页客户端用户界面中，通过Settings顶部菜单，选择Translations > Import/Export > Import Translation菜单项。

2. 在Import Translations对话框中，填写语言名称和代码，并选择要导入的文件。最后，点击Import按钮来执行导入：
   ![图11.10 – 导入翻译文件对话框](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021042514530869.png)图11.10 – 导入翻译文件对话框

3.  要通过Odoo命令行界面导入翻译文件，我们必须将它放至服务端的插件路径中，然后执行导入：

```
   $ mv myfile.po ./addons/
   $ ./odoo.py -d mydb --i18n-import="myfile.po" --lang=es_ES
   ```

### 运行原理...

Import Translation接受一个PO或CSV文件，并将翻译字符串导入到ir.translation数据表中。

网页客户端功能中要求填写语言名，但它并没有在导入过程中使用到。还有一个重写选项。如果勾选，会强制导入所有的翻译字符串，即便这些字符串已经存在，在这个过程中会进行覆盖。

在命令行中，导入可通过--i18n-import选项来实现。必须提供该文件相对插件路径目录的路径，-d和--language (或-l)也是必传的。还可以通过在命令行中添加--i18n-overwrite 选项来实现重写。注意我们在这里没有使用--stop-after-init选项。不需要使用，因为导入动作在完成时会停止服务。

## 对网站修改自定义URL语言代码

Odoo对网站应用也支持多语言。在网中，当前语言标记为语言字符串。本节中，我们学习如何在URL中修改语言代码。

### 准备工作

在学习本节前，请确保安装了website模块并且对网站启用了多语言。

### 如何实现...

按照如下步骤来修改语言的URL代码：

1. 通过Settings > Translations > Languages菜单项打开语言列表。点击一个已安装语言会打开如下的表单：
   ![图11.11 – 网站语言URL代码](https://i.cdnl.ink/homepage/wp-content/uploads/2021/03/2021042515035216.png)
   图11.11 – 网站语言URL代码
2. 这里可以看到URL Code字段。设置为所希望的值。不要添加空格或特殊字符。

配置完后，就可以对网站测试看结果了。打开首页并修改语言，就会在URL中看到自定义的语言代码。

### 运行原理...

Odoo通过URL路径来识别网站的语言。例如[www.odoo.com/fr_FR](http://www.odoo.com/fr_FR)用于法语，[www.odoo.com/es_ES](http://www.odoo.com/es_ES)用于西班牙语。这里URL中的fr_FR和es_ES部分是语言的ISO代码，在Odoo中用于监测请求的语言。但有时我们希望将语言设置为对用户更友好的方式。这时就可以更新URL Code字段。一旦做了修改，Odoo网站会使用URL Code的值来识别语言。例如，可以将法语的URL Code设置为 fr，那么[www.odoo.com/fr_FR](http://www.odoo.com/fr_FR)就会转化为[www.odoo.com/fr](http://www.odoo.com/fr)。

> 📝注：在生产环境中修改URL code不会有问题，Odoo会将ISO语言代码的URL跳转至自定义URL。

Adair520/odoo-cookbook

简介

发行版

贡献者

近期动态

Adair520/odoo-cookbook .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

Adair520/odoo-cookbook