title: "国际化" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - How To Guides - Repos - Data

国际化

什么是国际化？

国际化是为软件提供多语言支持的过程，在本文语境中特指 WordPress。国际化常被缩写为 i18n，其中 18 代表首字母 i 与末字母 n 之间的字符数。

为您的插件和主题提供 i18n 支持能让其触达最广泛的用户群体，甚至无需您亲自提供额外的语言翻译。当您将软件上传至 WordPress.org 时，所有 JS 和 PHP 文件都将被自动解析。检测到的翻译字符串会被添加至 translate.wordpress.org，供社区成员进行翻译，从而确保 WordPress 插件和主题能覆盖尽可能多的语言。

对于 PHP，WordPress 已建立长期成熟的流程，详见如何为插件实现国际化。随着 WordPress 5.0 的发布，JavaScript 代码的翻译流程也实现了类似机制。

如何在 JavaScript 中使用 i18n

WordPress 5.0 引入了 wp-i18n JavaScript 包，它提供了添加可翻译字符串所需的功能，就像在 PHP 中一样。

首先，在注册脚本时将 wp-i18n 添加为依赖项：

<?php
/**
 * Plugin Name: Myguten Plugin
 * Text Domain: myguten
 */
function myguten_block_init() {
    wp_register_script(
        'myguten-script',
        plugins_url( 'block.js', __FILE__ ),
        array( 'wp-blocks', 'react', 'wp-i18n', 'wp-block-editor' )
    );

    register_block_type( 'myguten/simple', array(
        'api_version' => 3,
        'editor_script' => 'myguten-script',
    ) );
}
add_action( 'init', 'myguten_block_init' );

在你的代码中，可以引入 i18n 函数。最常用的函数是 __（双下划线），它用于翻译简单字符串。以下是一个基本区块示例：

import { __ } from '@wordpress/i18n';
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';

registerBlockType( 'myguten/simple', {
    apiVersion: 3,
    title: __( 'Simple Block', 'myguten' ),
    category: 'widgets',

    edit: () => {
        const blockProps = useBlockProps( { style: { color: 'red' } } );

        return <p { ...blockProps }>{ __( 'Hello World', 'myguten' ) }</p>;
    },

    save: () => {
        const blockProps = useBlockProps.save( { style: { color: 'red' } } );

        return <p { ...blockProps }>{ __( 'Hello World', 'myguten' ) }</p>;
    },
} );

在上面的例子中，该函数将使用第一个参数作为要翻译的字符串。第二个参数是文本域，它必须与你的插件指定的文本域别名匹配。

可用的常用函数（这些函数与其 PHP 对应函数功能一致）：

__( 'Hello World', 'my-text-domain' ) - 翻译特定字符串。
_n( '%s Comment', '%s Comments', numberOfComments, 'my-text-domain' ) - 根据提供的数字翻译并获取单数或复数形式。
_x( 'Default', 'block style', 'my-text-domain' ) - 在特定上下文中翻译字符串。

注意： 所有展示给用户的字符串都应包裹在 i18n 函数中。

在代码中的所有字符串都被包裹后，最后一步是使用 wp_set_script_translations() 函数告诉 WordPress 你的 JavaScript 包含翻译。

<?php
    function myguten_set_script_translations() {
        wp_set_script_translations( 'myguten-script', 'myguten' );
    }
    add_action( 'init', 'myguten_set_script_translations' );

这就是使你的插件 JavaScript 代码可翻译所需的全部步骤。

当你为句柄设置脚本翻译时，WordPress 会自动判断 translate.wordpress.org 上是否存在翻译文件，如果存在，则确保在你的脚本运行前将其加载到 wp.i18n 中。通过 translate.wordpress.org，插件作者也无需担心建立自己的翻译基础设施，可以依赖拥有数十个活跃语言环境的全球社区。了解更多关于 WordPress 翻译的信息。

提供您自己的翻译

如果您具备足够的语言知识，可以随插件创建并发布自己的翻译，确保翻译内容可用。

创建翻译文件

翻译文件必须采用 JED 1.x JSON 格式。

要创建 JED 翻译文件，首先需要从文本中提取字符串。通常，语言文件都存放在插件的 languages 目录中。使用 WP-CLI，在插件目录中运行以下命令创建 .pot 文件：

mkdir languages
wp i18n make-pot ./ languages/myguten.pot

这将创建 myguten.pot 文件，其中包含项目中所有可翻译的字符串。

msgid ""
msgstr ""
"Project-Id-Version: Scratch Plugin\n"
"Report-Msgid-Bugs-To: https://wordpress.org/support/plugin/scratch\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"POT-Creation-Date: 2019-03-08T11:26:56-08:00\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"X-Generator: WP-CLI 2.1.0\n"
"X-Domain: myguten\n"

#. Plugin Name of the plugin
msgid "Scratch Plugin"
msgstr ""

#: block.js:6
msgid "Simple Block"
msgstr ""

#: block.js:13
#: block.js:21
msgid "Hello World"
msgstr ""

这里，msgid 是需要翻译的字符串，msgstr 是实际的翻译内容。在 POT 文件中，msgstr 始终为空。

然后，这个 POT 文件可以用作新翻译的模板。您应该复制文件并使用要翻译的语言代码，本例将使用世界语（eo）：

cp myguten.pot myguten-eo.po

对于这个简单的示例，您可以直接在编辑器中编辑 .po 文件，并为所有 msgstr 集添加翻译。对于更庞大、更复杂的翻译集，可以使用 GlotPress 和 Poedit 工具来协助。

您还需要添加 Language: eo 参数。以下是完整的已翻译 myguten-eo.po 文件：

# Copyright (C) 2019
# This file is distributed under the same license as the Scratch Plugin plugin.
msgid ""
msgstr ""
"Project-Id-Version: Scratch Plugin\n"
"Report-Msgid-Bugs-To: https://wordpress.org/support/plugin/scratch\n"
"Last-Translator: Marcus Kazmierczak <marcus@mkaz.com>\n"
"Language-Team: Esperanto <marcus@mkaz.com>\n"
"Language: eo\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"POT-Creation-Date: 2019-02-18T07:20:46-08:00\n"
"PO-Revision-Date: 2019-02-18 08:16-0800\n"
"X-Generator: Poedit 2.2.1\n"
"X-Domain: myguten\n"

#. Plugin Name of the plugin
msgid "Scratch Plugin"
msgstr "Scratch kromprogrameto"

#: block.js:6
msgid "Simple Block"
msgstr "Simpla bloko"

#: block.js:13 block.js:21
msgid "Hello World"
msgstr "Saltuon mundo"

创建翻译文件的最后一步是将 myguten-eo.po 转换为所需的 JSON 格式。为此，你可以使用 WP-CLI 的 wp i18n make-json 命令，该命令需要 WP-CLI v2.2.0 或更高版本。

wp i18n make-json myguten-eo.po --no-purge

这将生成 JSON 文件 myguten-eo-[md5].json，其内容如下：

{
    "translation-revision-date": "2019-04-26T13:30:11-07:00",
    "generator": "WP-CLI/2.2.0",
    "source": "block.js",
    "domain": "messages",
    "locale_data": {
        "messages": {
            "": {
                "domain": "messages",
                "lang": "eo",
                "plural-forms": "nplurals=2; plural=(n != 1);"
            },
            "Simple Block": [ "Simpla Bloko" ],
            "Hello World": [ "Salunton mondo" ]
        }
    }
}

加载翻译文件

最后一步是告诉 WordPress 在哪里可以找到翻译文件。wp_set_script_translations 函数接受一个可选的第三个参数，用于指定优先检查翻译文件的路径。例如：

<?php
    function myguten_set_script_translations() {
        wp_set_script_translations( 'myguten-script', 'myguten', plugin_dir_path( __FILE__ ) . 'languages' );
    }
    add_action( 'init', 'myguten_set_script_translations' );

WordPress 将检查该路径下格式为 ${domain}-${locale}-${handle}.json 的文件作为翻译源。或者，你也可以使用文件相对路径的 md5 哈希值代替注册的句柄，格式为 ${domain}-${locale}-${md5}.json。

使用 make-json 会自动以 md5 哈希值命名文件，因此可以直接使用。你也可以将文件重命名为使用句柄，这样文件名就会是 myguten-eo-myguten-script.json。

测试翻译

您需要将 WordPress 安装设置为世界语。前往设置 > 常规，将站点语言更改为世界语。

设置好语言后，创建一篇新文章，添加区块，您将看到所使用的翻译。

翻译过滤

翻译函数（__()、_x()、_n() 和 _nx()）的输出是可过滤的，完整信息请参阅国际化过滤器。

← 返回文档中心