### 测试翻译

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

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

### 过滤翻译

翻译函数（`__()`、`_x()`、`_n()` 和 `_nx()`）的输出是可过滤的，完整信息请参阅 [国际化过滤器](/docs/reference-guides/filters/i18n-filters.md)。

# 国际化

## 什么是国际化？

国际化是指为软件提供多语言支持的过程，在本文中特指 WordPress 的国际化。国际化通常缩写为 **i18n**，其中 18 代表首字母 _i_ 和末字母 _n_ 之间的字母数量。

为您的插件和主题提供 i18n 支持能够最大限度地扩大其受众范围，甚至无需您亲自提供额外的语言翻译。当您将软件上传至 WordPress.org 时，所有 JS 和 PHP 文件都将被自动解析。检测到的翻译字符串会被添加到 [translate.wordpress.org](https://translate.wordpress.org/)，供社区成员进行翻译，从而确保 WordPress 插件和主题能够支持尽可能多的语言。

对于 PHP，WordPress 已建立成熟的流程，请参阅[如何为您的插件进行国际化](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/)。随着 WordPress 5.0 的发布，JavaScript 代码的翻译也引入了类似流程。

## 如何在 JavaScript 中使用 i18n

WordPress 5.0 引入了 wp-i18n JavaScript 工具包，它提供了与 PHP 类似的翻译字符串所需功能。

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

```php
<?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 函数。最常用的函数是 **__**（双下划线），用于简单字符串的翻译。以下是一个基础区块示例：

```js
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' )` - 在特定上下文中翻译字符串。

<div class="callout callout-alert">
<strong>注意：</strong>所有向用户显示的字符串都应使用 i18n 函数进行包装。
</div>

当代码中的所有字符串都完成包装后，最后一步是使用 [wp_set_script_translations()](https://developer.wordpress.org/reference/functions/wp_set_script_translations/) 函数告知 WordPress 您的 JavaScript 包含翻译内容。

```php
<?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 翻译](https://make.wordpress.org/meta/handbook/documentation/translations/)的信息。

## 提供自定义翻译

若您具备相应语言知识，可通过插件创建并发布专属翻译，确保翻译内容的可用性。

### 创建翻译文件

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

创建 JED 翻译文件时，首先需要从文本中提取字符串。通常语言文件都存放在插件的 `languages` 目录中。通过 [WP-CLI](https://wp-cli.org/) 在插件目录执行以下命令创建 `.pot` 文件：

```bash
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）：

```bash
cp myguten.pot myguten-eo.po
```

对于简单示例，您可以直接在编辑器中修改 `.po` 文件，为所有 `msgstr` 添加翻译内容。对于更复杂的大型翻译项目，可使用 [GlotPress](https://glotpress.blog/) 和 [Poedit](https://poedit.net/) 工具辅助完成。

同时需要添加 `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` 命令](https://developer.wordpress.org/cli/commands/i18n/make-json/)（要求 WP-CLI v2.2.0 及以上版本）：

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

这将生成包含以下内容的 JSON 文件 `myguten-eo-[md5].json`：

```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
<?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`。