首页 / WordPress建站 / WordPress开发 / WordPress 5.0+ JavaScript本地化翻译
Loading收藏1

倡萌在《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时将脚本添加为依赖项:

1
2
3
4
5
6
wp_register_script(
	'my-plugin-script',
	plugins_url( 'js/my-script.js', __FILE__ ),
	array( 'wp-i18n' ),
	'0.0.1'
);

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

1
2
3
4
5
6
7
8
9
10
11
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 为每个脚本调用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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翻译文件如下所示:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
   "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.jsmy-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.phpjs/my-script.js 和js/my-block.js。您使用WP-CLI提取字符串并生成翻译目录(POT),如下所示:

1
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配置中

1
2
3
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配置中:

1
2
3
4
5
6
[
    '@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文件,如下所示:

1
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.gettexti18n.gettext_with_contexti18n.ngettext,和i18n.ngettext_with_context过滤器。要覆盖单个翻译,您可以像这样使用它们:

1
2
3
4
5
6
7
8
9
10
11
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以查看应该改进哪些可翻译字符串。

拓展阅读

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

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

你可能还喜欢

1 条评论

发表评论

我们是靠谱的WordPress建站团队!

专业承接WordPress网站建设及运维、WordPress主题和插件开发、汉化、安装等服务

联系电话:0773-8282430

查看所有服务项目

视频教程: 点击联系我们
定制开发: 点击联系我们
售后支持: 点击联系我们
商务合作: 点击联系我们

固话:0773-8282-430

手机:133-0773-9152

微信扫一扫,联系我们