如何国际化您的 WordPress 网站

2017 年 9 月 30 日，国际 WordPress 社区联合 24 小时翻译 WordPress 生态系统。 #WPTranslationDay 第三次将全天翻译马拉松与数字和贡献者日活动相结合，旨在提升为全球用户创造无障碍体验的价值，即众所周知的“本地化”。

作为一个开源社区，我们都应该努力将我们的开源贡献本地化。 不过，在您转录您的数字资产之前，您必须将您的代码库国际化。

“国际化”和“本地化”这两个术语经常互换使用，尽管它们在技术上代表了翻译过程的两个不同方面。

• 国际化 (I18N)是国际化或调整您的主题或插件以将其翻译成世界上任何语言的过程。
• 本地化 (L10N)是将您的国际化工具本地化或翻译成给定语言的后续过程。

WordPress 目前已完全本地化超过 65 种语言，并为另外 95 种语言环境提供部分翻译。 随着更多本地化的引入，国际使用量继续增加。

非英语 WordPress 用户在 2014 年超过了英语用户，随着#WPTranslateDay 等努力的增长，他们在 2017 年无意中继续稀释英语用户的比例。

随着 WordPress 在语言上变得越来越容易访问，I18N 和 L10N 的知识对于插件和主题开发人员在全球 WordPress 经济中蓬勃发展至关重要。 对于扩展业务，这些开发技能可以打开通往国外市场的大门。 Web 可访问性，包括语言可访问性，对业务有好处，对人们也更好。

作为#WPTranslationDay的延续，这里有一个更新的指南，用于国际化您的 WordPress 插件和主题。

这是我们今天将要探索的过程的简要概述。

• 发现
  • 了解翻译文件
    • 锅档
    • 采购订单文件
    • 莫文件
  • GlotPress 和语言包
  • 备份和准备您的环境
• 插件 I18N
  • 插件头
  • 加载文本域
  • 字符串审计
  • 生成 POT 文件
• 主题 I18N
  • 主题标题
  • 加载文本域
  • 字符串审计
  • 生成 POT 文件
• JavaScript I18N
• 其他资源

发现

了解翻译文件

WordPress 使用 GNU gettext 库来促进 I18N。

首先，让我们熟悉一下整个过程生成的gettext翻译文件。

可移植对象模板文件 (POT)

在 I18N 过程中，我们将使用一个工具来查找国际化字符串并生成一个POT 文件，其中包含您的插件和主题中的所有可翻译文本。

可移植对象文件 (PO)

从外观上看，POT 文件和PO 文件之间没有显着差异。 它们在语法上是相同的，只是根据它们的预期目的而有所不同。

生成 POT 文件后，文本字符串应由翻译器解释为您的首选语言。 PO 文件最终将包含您的母语的文本字符串以及相应的翻译。

机器对象文件 (MO)

最后，PO 文件被转换为机器可读的文档或机器对象文件。 该文件将存在于您的主题或插件目录中，以便 WordPress 在提供翻译版本时调用。

备份和准备您的环境

在修改任何标记之前，备份您的插件、主题或整个站点（无论您正在国际化什么！），并让您的开发环境井井有条。

如果您打算本地化您的网站，请务必进行快速插件审核。 删除或停用您不再积极使用的任何插件。 从长远来看，这种快速审核将为您节省时间。

国际化您的插件

插件头

首先，我们将更新插件标头。 具体来说，文本域和域路径。

示例插件头

/* Plugin Name: My Rad Plugin Plugin URI: https://myradplugin.com Description: Custom Plugin That Makes My Site Rad Author: Rad Plugin Creator Version: 1.0 Author URI: https://radplugincreator.com Text Domain: rad-plugin Domain Path: /languages/ */

文本域

文本域是 WordPress 识别属于插件的所有文本的唯一标识符，并且必须与插件的 slug 匹配。

如果您的插件托管在 WordPress.org 上，这一点尤其重要； 这些需要匹配，以便 GlotPress 为您的插件正确导入翻译。

在我们的示例中，插件文件名为rad-plugin.php ，文本域为rad-plugin

您可能已经设置了文本域。 如果不这样做，请记住使用连字符，而不是下划线。

域路径

域路径是最终翻译文件所在的文件夹。您应该在插件目录中创建一个新文件夹，例如/languages/ ，并更新域路径，以便 WordPress 确切知道在哪里搜索翻译文件。

加载文本域

接下来，我们将通过将以下函数添加到我们的代码中来加载文本域。

load_plugin_textdomain()

 load_plugin_textdomain( $domain, $abs_rel_path, $plugin_rel_path );

如果用户语言的翻译文件可用，加载文本域功能将告诉 WordPress 交付它。

参数

• $domain — 文本域（必需）
• $abs_rel_path — false （可选，已弃用）
• $plugin_rel_path — /languages/ （可选，这是包含翻译文件的目录的相对路径。在我们的示例中，/languages/。从 4.6 开始，WordPress 将在插件的 /languages/ 目录中搜索这些文件，如果这未指定。）

Rad 插件示例

要加载文本域，我们将挂钩到“plugins_loaded”操作。

 add_action( 'plugins_loaded', 'rad_plugin_load_text_domain' ); function rad_plugin_load_text_domain() { load_plugin_textdomain( 'rad-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' ); }

字符串审核

下一步是将插件的所有文本字符串包装在翻译函数中。

最常见的翻译函数是用于返回已翻译字符串的__()和用于回显已翻译字符串的_e() 。

Rad 插件示例

__() $text = __( 'Super Rad!', 'rad-plugin' );

此功能适用于简单的翻译。 它考虑了两个参数； 文本字符串和文本域。

 _e( 'Super Rad!', 'rad-plugin' );

该函数只是简单地回显该值。 否则，它的工作原理与前一个函数完全相同。

有许多额外的翻译功能也应该在适当的时候使用。

其他基本功能

__() _e() _x() _ex() _n() _nx() _n_noop() _nx_noop() translate_nooped_plural()

日期和数字功能

number_format_i18n() date_i18n()

转义函数

不要忘记使用以下转义函数转义正在输出的任何数据。

 esc_html__() esc_html__() esc_html_x() esc_attr__() esc_attr_e() esc_attr_x()

在我们的 Rad 示例中，我们可能有一行插件代码，如下所示：

 function create_section() { esc_html_e( 'Below are your settings for Rad Plugin', 'rad-plugin' ); }

创建一个锅文件

最后一步是创建一个 POT 文件。 有几种不同的工具可用于生成这种类型的文件，但在本教程中，我们将坚持 WordPress codex 的建议并使用 Poedit，这是一个易于使用的用于管理翻译的 GUI。

注意：如果您的插件或主题已经在 WordPress.org 存储库中，您可以跳过此过程并从管理页面生成一个 POT 文件。 在这种情况下，没有必要为每种语言生成一个 .po 文件。 2015 年引入 GlotPress 和语言包简化了翻译过程； GlotPress 只需要 .pot 文件，该文件将由 WordPress.org 导入并通过 translate.wordpress.org 仪表板提供给翻译人员。 来自世界各地的合作者将使用此仪表板在#WPTranslateDay 上提供翻译。

下载 Poedit

配置 Poedit

翻译属性

首先转到File > New 。 然后选择插件的母语并点击OK 。

接下来，选择目录>新建。 输入项目名称、版本、联系人和语言。

路径

接下来选择源路径选项卡。 如果这是一个新文件，您必须先保存该文件。

按照我们的示例，我们将选择File > Save As以将 .po 文件另存为 rad-plugin 内的 /languages/ 目录。 同样，文件名应与插件的 slug 匹配。

 rad-plugin.po

保存后，输入翻译文件所在目录的相对路径。在这种情况下， languages 。

关键词

选择来源关键字选项卡。 单击+ 图标以添加适当的函数名称。

备忘单

__ _e _x _ex _n _nx _n_noop _nx_noop translate_nooped_plural number_format_i18n date_i18n esc_html__ esc_html__ esc_html_x esc_attr__ esc_attr_e esc_attr_x

之后，您可以单击 OK ，然后单击File > Save 。

Poedit 将保存 .mo 和 .po 文件。 您可以通过复制 .po 文件并添加 .pot 扩展名来创建 .pot 文件。 国际用户可以使用模板 .pot 文件将字符串翻译成他们的语言。

国际化您的主题

主题国际化的过程实际上与插件的 I18N 相同。 我们将从检查主题标题开始，然后生成另一个 POT 文件。

主题标题

仔细检查您的主题标题以确保您的文本域和域路径已设置。

示例主题标题

/* Theme Name: Rad Theme Author: Rad Theme Author Text Domain: rad-theme Domain Path: /languages/ */

加载文本域

下一步是这次在主题的functions.php文件中加载一个文本域。

load_theme_textdomain()

 load_theme_textdomain( 'radtheme', get_template_directory() . '/languages' );

为了加载这些文件，您必须使用 after_setup_theme 操作注册它们。

 add_action( 'after_setup_theme', 'rad_theme_setup' ); function rad_theme_setup() { load_theme_textdomain( 'radtheme', get_template_directory() . '/languages' ); }

字符串审核

是时候进行另一个字符串审计了！ 此时您应该熟悉基本的翻译功能。

让我们看一些更棘手的翻译。

占位符

如果不使用占位符，PHP 变量（如以下示例）将无法正确翻译。

 echo "We added $count rad points.";

printf() & sprintf()

这些函数使用占位符（例如%s或%d表示整数）来插入包含动态内容的文本字符串。

Rad 主题示例

/* Translators: %d is the number of rad points added */ printf( esc_html__( 'We added %d rad points.', 'rad-plugin' ), $count );

复数

_n()函数可以处理更复杂的字符串翻译，如复数形式，但不推荐使用，因为它在翻译软件中存在限制。 相反，您可以编写一个简单的if 语句来区分单数和复数词。

Rad 插件示例

If ( 1 === $rad_points_found ) { $message = __( '1 rad point', 'rad-plugin' ); } else { /* Translators: %s is the number of rad points found */ $message = sprintf( __( '%s rad points' , 'rad-plugin' ) , $rad_points_found ); }

生成锅文件

生成主题 POT 文件的过程与生成插件 POT 文件的过程相同。 探索下面的一些方法。

命令行

安装 WordPress Trunk 和 gettext GNU 软件包后，您可以通过在命令行中运行makepot.php脚本轻松完成这一步。

打开命令行并导航到 I18N 工具目录。

 cd wpdev/tools/i18n/

该脚本应如下所示：

 php path/to/makepot.php wp-theme path/to/rad-theme rad-theme.pot

该脚本将完成它的工作，完成的文件rad-theme.pot将最终出现在当前目录中。

繁重的任务

创建 POT 文件的另一种方法是使用 grunt-wp-i18n 或 grunt-pot 运行 Grunt 任务。 像 Grunt 这样的任务运行器可以自动执行许多繁琐的任务，例如生成 POT 文件。

要创建 POT 文件，请确保首先安装了 node.js。 然后，通过命令行在你的语言目录中安装 Grunt，然后你就可以走了。 现在，您可以快速运行这些 I18N 命令并制作翻译文件，而无需离开舒适的命令行。

JavaScript I18N

如果您是现代主题或插件开发人员，您可能会使用 JavaScript 来处理项目的某些组件。 wp_localize_script是提取 PHP 数据以提供给脚本的有效函数，它是在 WordPress 中翻译 JavaScript 的唯一方法。

WP_LOCALIZE_SCRIPT()

该函数将允许我们在 PHP 中本地化字符串服务器端并将文本字符串作为 JavaScript 对象提供给脚本。

 wp_localize_script( $handle, $name, $data );

参数

• $handle — 数据需要可用的脚本句柄（必需 — 需要匹配此数据所在的脚本句柄，请参见下面的示例）
• $name — 包含数据的对象的名称（必需 — 应该是唯一的）
• $data — 传递给脚本的数据数组（必需） 。

RAD 插件示例

add_action( 'wp_enqueue_scripts', 'rad_theme_scripts' ); function rad_theme_scripts() { wp_enqueue_script( 'rad-theme-script', get_template_directory_url() . '/js/rad-theme-script.js' ); wp_localize_script( 'rad-theme-script', 'rad-I18n', array( 'message' => __( 'Super Rad!', 'rad-theme' ), ) ); }

在 JAVASCRIPT 中访问数据

下面的简单代码片段是如何在 JavaScript 文件中访问此数据的示例。

 alert( rad-I18n.message );

其他资源

• 面向 WordPress 开发人员的 I18N
• WordPress 主题手册：国际化
• WordPress 插件手册：国际化
• WordPress.tv：I18N

把它包起来

恭喜！ 您刚刚国际化了您的主题和/或插件，使所有母语的人都可以从中受益。 无论您的项目是通过 WordPress 存储库分发的，还是为您组织的网站定制开发的，从一开始就将文件国际化只有一个好处。

• 让您的开源贡献在全球范围内可访问。
• 与国外市场的新客户建立对话。
• 节省时间并减少将来费力的更新。

始终国际化。