WordPress 5.0+ JavaScript本地化翻译

倡萌在《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 --no-purge 即可生成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',
    },
]

倡萌提示：如果你对如何集成  Babel 和 配置 Webpack 不熟悉的话，建议你看看这篇文章：https://www.bluehost.com/blog/developers-corner/javascript-translations-in-gutenberg-9931/

注意：  您仍然希望为其他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以查看应该改进哪些可翻译字符串。

拓展阅读

• Dev Note关于新的JavaScript国际化支持
• 插件开发人员手册中的国际化最佳实践
• 古腾堡手册中的国际化部分

原文：Internationalization in WordPress 5.0，发布于 2018年12月20日，由 倡萌@WordPress大学 翻译，未经许可，禁止转载和挪用译文！

倡萌总结：javascript里的翻译字段，需要通过文章提到的手段提取生成 pot 文件，然后使用 poedit 软件导入 pot 翻译得到 .po 文件，然后通过 WP-CLI 命令或 po2json 将 po 的内容转换生成 json 文件，这样就完成了。