WordPress 5.0+ JavaScript本地化翻译的案例

摄影大咖 · 发表于 2019-10-25 12:07:05

亲注册登录道勤网-可以查看更多帖子内容哦！（包涵精彩图片、文字详情等）请您及时注册登录-www.daoqin.net

您需要登录才可以下载或查看，没有账号？立即注册

x

道勤小编在《wordpress 5.0+支持JavaScript i18n本地化翻译》中提到了WordPress对JavaScript本地化翻译的支持。今天道勤小编将和大家分享下来自 @Pascal Birchler 的文章《WordPress 5.0的国际化》，它比较全面的介绍了对JavaScript本地化翻译的整个实现方式，希望对各位开发者能有所帮助。

WordPress JavaScript国际化

WordPress 5.0 附带了一个名为Gutenberg的全新编辑器。这个新编辑器主要用JavaScript编写，这意味着很多国际化翻译都发生在客户端而不是服务器上。虽然WordPress核心以前是使用wp_localize_script() 函数来对UI界面的字段进行翻译的，但面对Gutenberg这样复杂的JavaScript插件，就需要更强大的解决方案了。

JavaScript本地化函数

WordPress 5.0 新增了JavaScript I18N 支持，也就是为JavaScript开发带来了类似于我们熟悉的PHP那样的函数，这启动一个新wp-i18n的JavaScript包，提供了新的函数 __()，_x()，_n()， _nx()，甚至sprintf()。这些函数和原有的PHP函数基本一致，可以以相同的方式使用。

要使用此包，您需要wp-i18n在注册JavaScript时将脚本添加为依赖项：

wp_register_script(
'my-plugin-script',
plugins_url( 'js/my-script.js', __FILE__ ),
array( 'wp-i18n' ),
'0.0.1'
);

复制代码

然后，本地化函数wp.i18n在JavaScript中的全局变量下可用。您可以像这样使用它们：

const { __, _x, _n, sprintf } = wp.i18n;
__( 'Hello World', 'my-plugin' );
_x( 'Glitter Box', 'block name', 'my-plugin' );
// 在你的js脚本的任何位置获取评论数量.
const commentCount = wp.data.select( 'my/data-store' ).getCommentCount();
/* translators: %s: number of comments */
sprintf( _n( 'There is %s comment', 'There are %s comments', commentCount, 'my-plugin' ), commentCount );

复制代码

这就是使JavaScript组件完全可本地化所需的全部内容。

如果您熟悉WordPress核心中的PHP翻译功能，您会发现缺少类似esc_html()或者esc_html__()。JavaScript中不需要这些，因为浏览器已经能够转义不安全的字符。

注意：虽然不鼓励在可翻译字符串中使用HTML，但有时这是必要的，例如添加链接（Check out this link to <a href="%s">my website</a>.）。现在，要做到这一点并不容易，至少在没有使用 innerHTML / dangerouslySetInnerHTML的情况下。目前，这个问题正在GitHub上进行讨论。

加载JavaScript翻译

请记住，仅使用 __() 函数族不足以使WordPress插件或主题完全国际化和本地化。我们还需要告诉WordPress 加载脚本的翻译。这可以通过使用WordPress 5.0中引入的新函数 wp_set_script_translations() 来实现。

该函数有三个参数：注册的脚本句柄（my-plugin-script 在前面的例子中），文本域（my-plugin），以及可选的包含翻译文件的目录的路径。仅当您的插件或主题未托管在WordPress.org上时才需要后者，WordPress.org会自动提供这些翻译文件。

注意：如果您需要为多个脚本使用 wp.i18n ，则必须通过 wp_set_script_translations 为每个脚本调用。

wp_register_script(
'my-plugin-script',
plugins_url( 'js/my-script.js', __FILE__ ),
array( 'wp-i18n' ),
'0.0.1'
);
wp_register_script(
'my-awesome-block',
plugins_url( 'js/my-block.js', __FILE__ ),
array( 'wp-i18n' ),
'0.0.1'
);
wp_set_script_translations( 'my-plugin-script', 'my-plugin' );
wp_set_script_translations( 'my-awesome-block', 'my-plugin' );

复制代码

这样做的原因是为了性能。只有在您的脚本实际入队列时才会加载翻译。如果是这种情况，WordPress会将翻译文件加载到内存中，并通过内联JavaScript提供wp.i18n。这意味着WordPress 每个脚本句柄需要一个翻译文件，每个文件只包含与该脚本相关的字符串。

想象一下，编写一个包含JavaScript的WordPress插件，其中包含许多不同的包，这些包也可以相互独立使用。如果您只需要单个包的那些翻译，则不希望加载所有翻译。

JavaScript翻译文件

我们已经介绍了如何加载JavaScript的翻译文件，但它们究竟有什么特别之处呢？好吧，这次我们不处理PO或MO文件，而是使用JSON文件。由于JSON可以在JavaScript中轻松读取，因此它是一种方便的格式来存储翻译。

此外，该 wp-i18n 软件包使用了一个与Jed JavaScript gettext库基本兼容的库，该库需要Jed风格的JSON转换数据。如上一节所述，WordPress.org会自动提供这些翻译文件。但是如果你想加载自己的翻译，你需要自己创建这样的JSON文件。

一个非常简单的Jed风格的JSON翻译文件如下所示：

{
"domain": "messages",
"locale_data": {
"messages": {
"": {
"domain": "messages",
"plural_forms": "nplurals=2; plural=(n != 1);",
"lang": "de_DE"
},
"Source": [
"Quelle"
],
"Enter the information for this recommendation.": [
"Gib die Informationen zu dieser Empfehlung ein."
],
"%s comment": [
"%s Kommentar",
"%s Kommentare"
],
"block name\u0004Recommendation": [
"Empfehlung"
]
}
}
}

复制代码

如果您已经熟悉PO翻译文件，则此格式包含了类似的信息，例如有关locale（de_DE）及其复数形式的信息。所有字符串都在messages对象中，原始作为键，翻译是值。如果一个字符串有一个额外的上下文，它就会被 \u0004 分隔符隔开。

注意：这里的一个重要细节是文本域，目前只能使用 messages ，而不是您在代码中实际使用的域。这里有一个WordPress Trac 工单，未来可能会支持使用实际的文本域。

JavaScript翻译文件名

WordPress中的PO和MO翻译文件通常具有格式$textdomain-$locale.po，例如my-plugin-de_DE.po。但对于JSON文件，情况有点不同。

您可能还记得我们需要将脚本句柄名称传递给wp_set_script_translations()。此句柄（handle）也需要添加搭配json文件名$textdomain-$locale-$handle.json。

因此，针对我们的my-plugin-script 脚本句柄，需要将翻译文件命名为my-plugin-de_DE-my-plugin-script.json。

由于技术原因，WordPress还会在表单中查找文件$textdomain-$locale-$md5.json，其中$md5 包含JavaScript文件名的MD5哈希值，包括扩展名。在前面的例子中，my-plugin-script 指向js/my-script.js。my-script.js 的MD5哈希值是537607a1a008da40abcd98432295d39e。所以我们的翻译文件也可以命名为my-plugin-de_DE-537607a1a008da40abcd98432295d39e.json。

生成JavaScript翻译文件

由于WordPress每个脚本句柄需要一个翻译文件，每个文件只包含与该脚本相关的字符串，这就意味着要处理大量的JSON文件。幸运的是，没有必要手工编写这些内容。

生成JSON翻译文件的推荐方法是使用WP-CLI。最新版本WP-CLI 2.1.0 为此提供了专用命令 wp i18n make-json 。

该wp i18n make-json命令可以从常规PO翻译文件中提取所有JavaScript字符串，并将它们放入单独的JSON文件中。

注意： WP-CLI 2.1.0已于12月18日发布。请确保您通过运行 wp cli update 使用最新版本。您可以使用 wp cli version 检查当前版本。

让我们假设在你的插件文件夹my-plugin 有三个源文件：my-plugin.php，js/my-script.js 和js/my-block.js。您使用WP-CLI提取字符串并生成翻译目录（POT），如下所示：

wp i18n make-pot my-plugin my-plugin/languages/my-plugin.pot

复制代码

使用 poedit 软件就可以将生成的.pot文件，翻译并生成所需的PO和MO文件。假设我们首先添加德语翻译my-plugin/languages/my-plugin-de_DE.po。之后，您只需运行wp i18n make-json my-plugin/languages 即可生成JavaScript翻译文件。结果如下：

一个新 my-plugin/languages/my-plugin-de_DE-537607a1a008da40abcd98432295d39e.json文件包含的翻译my-script.js。
一个新 my-plugin/languages/my-plugin-de_DE-dad939d0db25804f91959baeec56ea8a.json 文件包含的翻译 my-block.js。
在my-plugin/languages/my-plugin-de_DE.po现在只包含了需要在服务器端的翻译。

如果您不想修改PO文件，请将--no-purge 参数传递给WP-CLI命令，如文档中所述。

注意：这些WP-CLI命令在一些特殊的情况中存在一些已知问题。当我们了解人们如何使用它们时，我们一直致力于改进工具。

提高效率的工具

WordPress 5.0 和 Gutenberg 引入的这些新流程在开始时会感觉有点复杂。为了让生活更轻松，我想分享一些项目配置的提示和技巧。

Webpack配置

如果您需要在任何地方引用项目中的全局变量 wp.i18n，那您不会满足于代码编辑器显示类型提示之类的内容。要改变这种情况，我建议安装 @wordpress/i18n 包作为使用 npm / yarn 的依赖项。然后你就可以在整个项目中使用 import { __ } from '@wordpress/i18n; 。

通常，这会使 Webpack 将库与您的代码捆绑在一起。由于WordPress已经通过wp.i18n 全局公开了库，因此不需要代码重复。要防止这种情况，请将以下内容添加到Webpack配置中：

externals: {
'@wordpress/i18n': { this: [ 'wp', 'i18n' ] }
}

复制代码

这样您就可以从IDE的功能以及已有的wp.i18n全局功能中受益。只需确保在 wp_register_script() 调用时添加 wp-i18n 为依赖项。

Babel 集成

在上一节中，我提到了使用wp i18n make-pot创建必要的翻译目录pot，您可以从中创建实际的本地化。根据您的开发人员工作流程，您可能希望调用使用Babel的构建工具@wordpress/babel-plugin-makepot来创建POT文件。下来就分享下与Babel集成以提取I18N方法。

下来，请运行npm install --save-dev @wordpress/babel-plugin-makepot 目录并将下面的代码添加到您的Babel配置中：

[
'@wordpress/babel-plugin-makepot',
{
output: 'languages/my-plugin-js.pot',
},
]

复制代码

注意：您仍然希望为其他PHP文件创建POT文件，而不仅仅是JavaScript文件。您仍然可以使用WP-CLI执行此操作。只需跳过JavaScript字符串提取并合并生成的POT文件，如下所示：

wp i18n make-pot my-plugin my-plugin/languages/my-plugin.pot --skip-js --merge=my-plugin/languages/my-plugin-js.pot

复制代码

在这种情况下，languages/my-plugin-js.pot只是暂时性的，所以你可以在之后再次删除它。

可用挂钩和过滤器

WordPress 提供了load_textdomain 和 gettext 这样的过滤器允许重写翻译文件路径或个人翻译。

在WordPress 5.0.2中，添加了以下过滤器用于更改 wp_set_script_translations() 的结果，因此您可以对JavaScript翻译执行相同操作：

pre_load_script_translations：预过滤给定文件，脚本句柄和文本域的脚本转换。这样，您可以将脚本转换逻辑短路以返回您自己的翻译。
load_script_translation_file：过滤用于加载给定脚本句柄和文本域的脚本转换的文件路径。
load_script_translations：过滤给定文件，脚本句柄和文本域的脚本转换。这样，您可以在从翻译文件加载翻译后覆盖翻译。

除此之外， pull request #12517 还对古登堡项目的 @wordpress/i18n 包增加了i18n.gettext，i18n.gettext_with_context，i18n.ngettext，和i18n.ngettext_with_context过滤器。要覆盖单个翻译，您可以像这样使用它们：

wp.hooks.addFilter(
'i18n.gettext',
'myplugin/filter-gettext',
function( translation, text, domain ) {
if ( 'Source' === text && 'foo-domain' === domain ) {
return 'New translation';
}
return translation;
}
);

复制代码

WordPress PHP国际化

在这篇文章中，我们提及了很多的JavaScript翻译，你可能想知道我们是否也改变了PHP方面的东西。答案是：没有。

但是，现在是为您的插件或主题进行某种I18N清洁的好时机。以下是一些有用的信息：

确保在主插件文件/主题样式表中设置了 Text Domain，并在整个项目中使用相同的文本域。
如果您的WordPress插件或主题托管在WordPress.org上并需要WordPress 4.6或更高版本（通过Tested up to自述文件中的标题指示），则无需调用load_plugin_textdomain()。
您可以运行wp i18n make-pot --debug以查看应该改进哪些可翻译字符串。

道勤主机提供365天*24小时全年全天无休、实时在线、零等待的售后技术支持。竭力为您免费处理您在使用道勤主机过程中所遇到的一切问题! 如果您是道勤主机用户，那么您可以通过QQ【792472177】、售后QQ【59133755】、旺旺【诠释意念】、微信：q792472177免费电话、后台提交工单这些方式联系道勤主机客服！如果您不是我们的客户也没问题，点击页面最右边的企业QQ在线咨询图标联系我们并购买后，我们为您免费进行无缝搬家服务，让您享受网站零访问延迟的迁移到道勤主机的服务！