自2007年以来,WordPress一直支持PHP的文本字符串翻译。截至2018年,我们已经有了一个类似的翻译JavaScript的字符串的过程。
通常,WordPress开发人员使用wp_localize_script()函数将翻译后的字符串从PHP传递到JavaScript。不幸的是,这种方法不能很好地扩展,并且会产生一些混乱的代码。得益于Gutenberg的到来,我们现在有了新的WordPress i18n npm库。
在撰写本文时,很难找到如何在WordPress中从头到尾正确翻译JavaScript字符串的例子。大多数例子会给您一个难题,但不会给您整个过程。我们今天的目标是记录从开始到结束的整个过程。
国际化和本地化概述
翻译过程分为两个步骤:国际化和本地化。
在提到国际化和本地化时,通常会看到缩写i18n和l10n。这背后的逻辑是,您取单词的第一个字母和最后一个字母,计算剩下的字母,然后把这个数字放在中间。
从最基本的层面来看,国际化是为翻译准备主题或插件的过程。本地化是利用这种准备并实际执行翻译的过程。
国际化始于WordPress提供的翻译功能。本质上,所有这些函数都允许您提供一个要翻译的文本字符串以及所谓的文本域。
Text Domain——一个命名空间,或唯一标识符,您所翻译的所有字符串都管理在这个命名空间中。WordPress使用文本域来区分主题或插件的翻译与另一个插件的翻译。
最后,使用自动化工具来定位和编译文本域中的所有文本字符串,并将其编译到.pot(便携式对象模板)文件中。
本地化是下一个步骤,当您将.pot文件提供给翻译器,以将其翻译成所选的语言时,就开始了。翻译器将接收该文件,翻译字符串,并将翻译后的字符串保存到.po(可移植对象)文件中。但是,WordPress需要一个.mo(机器对象)文件,以便通过代码动态地翻译文本。
最后一步是将.po文件转换为.mo文件。有很多种方法可以实现,但是如果您使用Poedit这样的工具,那么这两个文件可以同时生成。
此时,我们已经为翻译做好了准备,并且有一个文件允许WordPress通过代码翻译字符串。但是,除非WordPress知道正在使用的语言以及语言文件的位置,否则不会翻译任何内容:
1. 设置语言——进入WordPress“设置”-》“通用”并从“网站语言”下拉列表中选择想要的语言,以此告诉WordPress您想要使用什么语言。虽然您的用户通常都是这样做的,但是您应该试试,彻底测试您的翻译是否在正常工作。
2. 注册您的语言文件——WordPress有几个函数,您可以使用它们来注册您的语言文件,这样您就可以找到它。如果您要翻译主题,您可以使用load_theme_textdomain()。如果您正在翻译插件,您可以使用load_plugin_textdomain()。
翻译JavaScript字符串
既然我们已经清楚地了解了WordPress中的翻译是如何工作的,让我们来看看我们如何用JavaScript翻译字符串。
使用WordPress i18n软件包
首先来看一下JS中的翻译函数:
__( ‘Hello World!’, ‘text-domain’ );
看起来很眼熟,是吗?JavaScript i18n API反映了通常在PHP中使用的翻译函数。唯一的例外是,您需要首先将WordPressi18n NPM库加载到您的项目中,并导入必要的函数激活它们。
因此,请先安装npm模块:
npm install –save @wordpress/i18n
接下来,从模块中导入将要使用的函数:
import { __, _n, sprintf } from ‘@wordpress/i18n’;
注意:此方法使用JavaScript ES6。有必要运行自动化构建过程,将代码转换为浏览器安全的JavaScript。我们建议使用Babel和Webpack。
生成.pot文件
通常,为PHP文件中的字符串生成.pot文件通常是使用Grunt任务运行器和grunt-wp-i18n包完成的。但是,该工具不扫描JavaScript文件。
WordPress发布了一个名为babel-plugin-makepot的NPM包,专门用于在您更改JavaScript文件时自动生成(或更新)一个.pot文件。
这个Babel插件需要使用Babel。通常,Babel被配置为通过Webpack运行。
因此,首先安装npm模块:
npm install –save-dev @wordpress/babel-plugin-makepot
接下来,更新您的Babel加载程序配置,以包含makepot插件:
[ “@wordpress/babel-plugin-makepot”, {
“output”: “languages/myplugin.pot”
} ]
如果您不熟悉Babel或Webpack,所有这些都会让您感到困惑。当第一次学习某件事时,看操作示例会更容易上手。也许查看这个webpack.config.js文件会有帮助。
设置好这个软件包后,运行Webpack,然后Webpack将监视JavaScript文件的更改,在使用翻译函数时自动检测,并将在语言/目录中自动生成或保持您的.pot文件为最新版本。
加载翻译文件
实际上,将.pot文件转换为.mo文件之后,就可以用传统的方法在WordPress中注册翻译文件了。
在插件中:
load_plugin_textdomain( ‘text-domain’, plugin_basename( __DIR__ ) 。 ‘/languages’ );
} );
在主题中:
load_theme_textdomain( ‘text-domain’, get_template_directory() 。 ‘/languages’ );
将翻译传输到JavaScript
WordPress将通过PHP加载我们的.mo文件,这就足以确保PHP中的任何字符串都被翻译了。然而,由于我们试图在JavaScript中翻译字符串,我们仍然还有一个障碍。我们需要将PHP知道的翻译传递给前端的JavaScript。
与使用wp_localize_script()将翻译后的字符串传递给我们的JavaScript的旧方法非常相似,我们需要确保弥合后端和前端之间的差距。
注意:在编写本文时,下面的代码依赖于网站上安装和激活的WordPress Gutenberg插件。新的Gutenberg WordPress编辑体验进入核心之后,就不会有插件依赖性,但是其中一些函数可能有稍微不同的名称。然而,JavaScript翻译的大多数当前用例都是在创建Gutenberg块的背景下进行的。
WordPress i18n JavaScript库目前被加载到JavaScript中的wp全局变量下。这意味着,为了访问WordPress中的i18n库,您应该这样做:wp.i18n。
我们想做的是利用WordPress i18n库中的setLocaleData() API调用来注册我们的翻译:
‘my-script-js’,
plugins_url( “/assets/js/script{$suffix}.js”, __FILE__ ),
[ ‘wp-i18n’ ],
filemtime( __DIR__ 。 “/assets/js/script{$suffix}.js” )
);
if
( function_exists( ‘gutenberg_get_jed_locale_data’ ) ) {
$locale = gutenberg_get_jed_locale_data( ‘text-domain’ );
$content = ‘wp.i18n.setLocaleData( ’ 。 json_encode( $locale ) 。 ‘, “text-domain” );’;
wp_script_add_data( ‘my-script-js’, ‘data’, $content );
}
在本例中,我们要将脚本加载到wp_enqueue_scripts钩子上。如果您正在创建一个Gutenberg块,您可以使用enqueue_block_assets或enqueue_block_editor_assets钩子。
为了遵循最佳实践,我们确保根据SCRIPT_DEBUG常量的状态加载缩小的或未缩小的JavaScript代码。
我们注册了定制脚本并给它一个句柄(在本例中为my-script-js)。只有在我们注册或查询脚本之后,我们才能调用wp_script_add_data(),这允许我们用JavaScript文件注册自定义数据。从本质上说,它将输出并运行我们提供的任何JavaScript代码,但只能在加载文件时使用。
我们要运行的JavaScript代码是wp.i18n.setLocaleData(),它将传递本地语言环境数据和我们的自定义文本域。我们正在使用PHP设置JavaScript代码,这样我们就可以轻松地将翻译从后端传递到前端。
正如您所看到的,我们正在使用gutenberg_get_jed_locale_data()函数,该函数接受文本域并以setLocaleData() JavaScript方法期望的结构返回翻译数据。我们使用json_encode()来确保我们将PHP数组转换成JSON,我们很乐意!
注意:为了更好地度量,我们将对gutenberg_get_jed_locale_data()的调用包装在function_exists()函数中,以防Gutenberg插件没有被激活,或者WordPress在Gutenberg被整合进内核后改变了函数名。在这两种情况下,它都将禁用JavaScript翻译。
更多内容推荐:>>>WordPress小部件及其使用方法 Gutenberg:新的WordPress编辑器