gutenbergdocs/how-to-guides/internationalization.md

测试翻译

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

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

过滤翻译

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

国际化

什么是国际化？

国际化是指为软件提供多语言支持的过程，在本文中特指 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
/**
 * 插件名称：Myguten 插件
 * 文本域：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: __( '简单区块', 'myguten' ),
	category: 'widgets',

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

		return <p { ...blockProps }>{ __( '你好世界', 'myguten' ) }</p>;
	},

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

		return <p { ...blockProps }>{ __( '你好世界', 'myguten' ) }</p>;
	},
} );

在上述示例中，该函数将使用第一个参数作为要翻译的字符串。第二个参数是文本域，必须与插件指定的文本域标识符匹配。

常用函数（这些函数与它们的 PHP 版本相对应）包括：

• __( '你好世界', 'my-text-domain' ) - 翻译特定字符串。
• _n( '%s 条评论', '%s 条评论', numberOfComments, 'my-text-domain' ) - 根据给定数字翻译并返回单数或复数形式。
• _x( '默认', '区块样式', '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: 全名 <邮箱@地址>\n"
"Language-Team: 语言团队 <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: 年-月-日 时:分+时区\n"
"X-Generator: WP-CLI 2.1.0\n"
"X-Domain: myguten\n"

#. 插件名称
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
# 本文件遵循与 Scratch 插件相同的许可协议进行分发。
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"

#. 插件名称
msgid "Scratch Plugin"
msgstr "Scratch 扩展插件"

#: block.js:6
msgid "Simple Block"
msgstr "简单区块"

#: block.js:13 block.js:21
msgid "Hello World"
msgstr "世界你好"

创建翻译文件的最后一步是将 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": [ "简单区块" ],
			"Hello World": [ "世界你好" ]
		}
	}
}

加载翻译文件

最后一步是告知 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 将按照 ${域名}-${语言代码}-${句柄}.json 的命名格式在该路径下查找翻译文件。此外，除了使用注册的句柄，也可使用文件相对路径的 md5 哈希值，格式为 ${域名}-${语言代码}-${md5}.json。

使用 make-json 命令会自动生成带 md5 哈希值的文件名，可直接使用。您也可以将文件重命名为使用句柄的形式，此时文件名应为 myguten-eo-myguten-script.json。