全书完整目录请见:Odoo 12开发者指南(Cookbook)第三版
本章中,我们将讲解如下内容:
- 安装语言及配置用户首选项
- 配置语言相关设置
- 通过网页客户端用户界面翻译文本
- 将翻译字符串导出到文件
- 使用gettext工具来简化翻译
- 将翻译文件导入到Odoo中
这里的很多操作可以通过网页客户端用户界面或命令行来完成。在可以使用的地方,我们会告诉你使用的方法。
安装语言及配置用户首选项
Odoo已预置了本地化,也就是说它支持多语言和本地化设置,如日期和数字格式。
初次安装时,仅能使用默认语言英语。要对用户开放其它语言和地点,需要先安装这些语言。
准备工作
我们需要启用开发者模式。如未启用请参照第一章 安装Odoo开发环境中激活Odoo开发者工具一节进行激活。
如何实现…
按照如下步骤在Odoo实例中安装新的语言:
- 选择Settings > Translations > Load a Translation菜单项。在出现的对话框中选择从可用语言列表中要安装的语言。如果安装了Website,还可以对网站可用的语言:
TODO - 这时点击Load按钮就会开始安装语言:
TODO - 新语言也可以通过命令行来安装。与上一步同等的命令如下:
1$ ./odoo-bin -d mydb --load-language=es_ES - 要设置用户使用的语言,访问Settings > Users & Companies > Users,在用户表单的首选项(Preferences)标签中设置语言(Language)字段的值。在同一界面还可以设置用户的时区:
TODO
用户也可以通过Preferences菜单项来进行这些配置。点击网页客户窗口右上角的用户即可。
运行原理…
用户可以有自己的语言和时区首选项。前者用于将用户界面的文本翻译为所选的语言并按本地习惯应用浮点和货币字段。
在语言可供用户选择之前,它必须通过Load a Translation功能进行过安装。可用语言列表可通过Settings > Translations > Languages菜单项进行查看。带有active标记的语言是已安装的。
每个Odoo插件模块负责它自己的翻译资源,位于i18n子目录中。每种语言的数据应放在 .po文件中。在我们的示例中,西班牙语的翻译文件通过es_ES.po数据文件进行加载。
Odoo还支持基语言(base language)的概念。例如,如果西班牙语的es.po文件,也有墨西哥西班牙语的es_MX.po 文件,那么es.po会作为es_MX.po的基语言。在安装了西班牙语的时候,两个数据文件都会被加载,先安装基语言,再安装指定的语言。因此,具体语言的翻译文件仅需包含针对语言不同部分的字符串,在本例中即为墨西哥西班牙语。
i18n子目录中还应包含 .pot文件,提供一个翻译的模板并包含所有的可翻译字符串。本章中将翻译字符串导出到文件一节讲解了如何导出可翻译字符串生成该文件。
在安装了其它语言时,对应的资源从所有安装的插件模块中载入并在Translated Terms模型中保存。它的数据可以在 Settings > Translations > Application Terms > Translated Terms 菜单项(注意仅在开发者模式下可见)中进行查看(和编辑)。
已安装语言的翻译文件还在新插件模块中安装或已有插件模块升级时才会被载入。
扩展知识…
通过重复Load a Translation操作即可在无需升级插件模块的情况下重新载入翻译文件。如果升级了翻译文件而又不想经历升级模块(及其所有依赖)的麻烦时可以使用这种方法。
如未勾选 Overwrite Existing Terms复选框,仅有新翻译的字符串被加载。因此,修改的已翻译字符串不会被加载。如果你希望已存在的翻译也被加载则勾选复选框,这样会覆盖当前已加载的翻译。注意这样在有人通过用户界面手动修改翻译时可能会导致问题。
存在前面的复选框是因为我们可以通过进入Settings > Translations > Application Terms > Translated Terms菜单项或在调试菜单中使用Technical Translation快捷选项来编辑指定的翻译。以这种方式添加或修改的翻译不会被覆盖,除非所重新加载的语言内时勾选了Overwrite Existing Terms。
同时插件模块可以在i18n_extra子文件夹中带有额外的翻译文件。首先, 下载了i18n子目录中的 .po文件。然后Odoo ORM为基语言下载了文件,然后对变种语言进行了下载。按照这个顺序,下载了i18n_extra子目录中的.po文件,首先下载基语言,然后下载语言变种。最后加载的字符串翻译即为在使用的。
配置语言相关设置
语言和它们的变种(如墨西哥西班牙语)也提供本地化设置,如日期和数字格式。
它们都有相应的默认值,只要用户使用正确的语言,本地化设置就应该是正确的。
但是你可能会想要修改语言的设置。比如,你可能会偏向于在用户界面中使用默认的英语,但又希望将美式英语的默认日期和数字格式匹配自己的要求。
准备工作
我们需要启用开发者模式。如未启用请参照第一章 安装Odoo开发环境中激活Odoo开发者工具一节进行激活。
如何实现…
按照如下步骤来修改语言的本地化设置:
- 选择Settings > Translations > Languages菜单项有检查所安装的语言和它们的设置。点击所安装的一种语言会打开带有相应设置的表单:
TODO - 编辑语言设置。修改日期为ISO格式,将日期格式修改为%Y-%m-%d.。要修改数字格式来使用逗号作为十进制分隔符,修改对应的十进制分隔符和千分位分隔符。
运行原理…
在登录并创建新的Odoo用户会话时,用户首选项中勾选了用户语言并在lang上下文键中进行了设置。然后使用它来格式化对应的输出 – 源文本翻译 为用户语言,日期和数字以语言的当前本地化设置进行格式化。
扩展知识…
服务端进程可修改动作所运行的上下文。例如,要获取根据美式英语格式设置了日期格式的记录,并独立于当前用户的语言首选项,可以进行如下操作:
1 |
en_records = self.with_context(lang='en_US').search([]) |
更多详情,请参见第九章 高级服务端开发技巧中的使用变更的上下文调用方法一节。
通过网页客户端用户界面翻译文本
进行翻译最简单的方式是使用由网页客户端提供的翻译功能。这些翻译字符串在数据库存储,稍后改导出为 .po文件,要么在插件模块中包含,要么稍后可进行手动导入。
文本字段可以有可翻译内容,也就是说它们的值可以依赖于当前用户的语言。我们还将学习如何在这些字段中设置依赖于语言的值。
准备工作
我们需要启用开发者模式。如未启用请参照第一章 安装Odoo开发环境中激活Odoo开发者工具一节进行激活。
如何实现…
我们将使用用户组作为示例来演示如何通过网页客户端翻译词语:
- 导航至你想要翻译的页面。作为示例,我们将通过Settings > Users & Companies > Groups菜单项打开组的视图。
- 在顶部菜单栏中,点击调试图标并选择Technical Translation选项:
TODO - 会显示针对该视图的可翻译词语的列表。编辑各行的Translation Value来修改(或添加)其翻译文件。如果要查找某个具体的源字符串,可使用所列出的过滤器来缩减所显示的文本:
TODO
组名是可翻译字段。我们来将记录值翻译为所安装的不同语言。 - 再次导航至User Groups菜单项,在表单视图中打开其中一条组记录,并点击Edit:
TODO - 注意在Name字段的最右端有一个特殊的图标。这表示它是一个可翻译字段。点击该图标以不同的安装语言打开翻译列表。这允许我们为每种语言设置翻译。
运行原理…
翻译词汇在ir.translation模型的数据表中进行存储。调试菜单下的Technical Translation选项提供对这些词汇的快速访问,与当前所选择的视图保持对应。
类似地,带有可翻译内容的模型字段可包含一个访问已安装语言列表的图标并为每种语言设置相应的值。
另外,可以使用Translations > Application Terms > Translated Terms菜单项来从Settings顶部菜单访问翻译词汇。这里,我们可以看到所有针对我们实例的可用词汇。应使用数据过滤器来定义想要找到的词汇。
扩展知识…
在Translated Terms菜单项那里,还可以找到Generate Missing Terms选项。选择它会显示一个对话窗口来显示所想要的语言,然后启动一个进程来从已安装的插件模块中提取可翻译的字符串并将新的内容添加到Translated Terms表格中。它与执行导出翻译的步骤作用相同,参见本章中将翻译字符串导出到文件一节中的讲解。
在修改一些模型或视图后这会非常有用。这么做会添加新字符串,这样我们就可以对它们进行翻译。
它也可用于从默认en_US语言中获取字符串。然后我们可以利用翻译词汇来替换原英文文本为更适用于用户具体业务的词汇。
ℹ️在主网站语言外的语言中编辑QWeb视图时,会注意到你只能修改字符串。这是因为在其它语言中,你实际上只能使用Odoo的国际化机制向节点的文本内容添加翻译。
将翻译字符串导出到文件
翻译可以对所选语言带有或不带有翻译文本进行导出。可以在模块中包含i18n数据,或者稍后通过文本编辑器或是专业工具来执行翻译。
我们将演示如何使用标准mail模块来进行导出,读者可以修改为自己想要进行导出的模块。
准备工作
我们需要启用开发者模式。如未启用请参照第一章 安装Odoo开发环境中激活Odoo开发者工具一节进行激活。
如何实现…
按照如下步骤来对mail插件模块导出翻译词汇:
- 在网页客户端用户界面的Settings顶级菜单中选择Translations > Import/Export > Export Translation菜单项。
- 在Export Translations对话框中,选择所要导出翻译的语言、文件格式以及要导出的模块。要导出翻译模板文件,从Language下拉列表中选择New Language (Empty translation template)。推荐使用 .po格式并且一次只导出一个插件模块 – 本例中为Discuss模块(mail是Discuss应用的技术名称):
TODO - 完成导出处理后,会显示一个新的窗口,包含一个下载文件的链接以及一些附加的建议。
- 通过Odoo命令行界面导出mail插件模块的翻译模板文件,键入如下命令:
12$ ./odoo-bin -d mydb --i18n-export=mail.po --modules=mail$ mv mail.po ./addons/mail/i18n/mail.pot - 若要通过Odoo命令行界面导出某种语言的翻译模板文件 – 本例中为针对西语的es_ES,键入如下命令:
12$ ./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格式可用于使用电子表格执行翻译,但在插件模块中所使用的格式是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文件中,应确保使用如下语句进行导入:
1 |
from odoo import _ |
然后它在用到要翻译的文本时可以这样使用:
1 |
_('Hello World') |
对于那些要使用额外上下文信息的字符串,我们应使用Python的字符串内插,如下所示:
1 |
_('Hello %s') % 'World' |
注意内插应放在翻译函数的外面。例如,_(“Hello %s” % ‘World’)是错误的。字符串内插最好应为字符串拼接,这样每个界面文本也仅是一个翻译字符串。
ℹ️对Selection字段要保持警惕!如果你对字定义传递了明确的值列表,显示的字符串会自动标记为翻译。另一方面,如果你传递一个返回值列表的方法,显示字符串必须显式地标记出翻译。
对于手动翻译工作,可以使用任何文本编辑器,但使用特别支持PO文件语法的编辑器会减少格式上的错误,让任务变得轻松。这类编辑器如下所示:
- POEDIT: https://poedit.net/
- Emacs (PO-mode): 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插件模块中创建的my_library是一个不错的对象。但是,请随意替换为你自己手边的其它自定义模块,将本节中的my_library替换为相应模块即可。
如何实现…
要通过命令行来管理翻译,假定Odoo的安装位置为~/odoo-work/odoo,执行如下步骤:
- 创建一个目标语言如西语翻译词语的汇总。如果我们的汇总文件名为odoo_es.po,应编写如下代码:
12$ cd ~/odoo-work/odoo # 使用你Odoo安装的路径$ find ./ -name es_ES.po | xargs msgcat --use-first | msgattrib -- translated --no-fuzzy -o ./odoo_es.po - 通过Odoo命令行界面导出该插件模块的翻译模板文件并将其放在模块中所需要位置:
12$ ./odoo-bin -d mydb --i18n-export=my_module.po --modules=my_module$ mv my_module.po ./addons/my_module/i18n/my_module.pot - 如果对目标语言还没有翻译文件,他过一个PO翻译文件,复用我们在汇总中已发现和翻译的词语:
123$ msgmerge --compendium ./odoo_es.po -o./addons/my_module/i18n/es_ES.po \/dev/null ./addons/my_module/i18n/my_module.pot - 如果翻译文件存在,在汇总中添加翻译:
1234$ 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 - 在PO文件中查看未翻译的词语,使用如下命令:
1$ msgattrib --untranslated ./addons/my_module/i18n/es_ES.po - 使用你喜欢的编辑器完成翻译。
运行原理…
第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开发环境中激活Odoo开发者工具一节进行激活。我们还会需要一个po翻译文件,在本节中我们将进行导入,例如myfile.po文件。
如何实现…
按照如下步骤来导入翻译词语:
- 在网页客户端用户界面中,通过Settings顶部菜单,选择Translations > Import/Export > Import Translation菜单项。
- 在Import Translations对话框中,填写语言名称和代码,并选择要导入的文件。最后,点击Import按钮来执行导入动作:
TODO - 要通过Odoo命令行界面导入翻译文件,我们必须将它放在服务端的插件路径中,然后执行导入:
12$ 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选项。不需要使用,因为导入动作在完成时会停止服务。