231 lines
8.7 KiB
Markdown
231 lines
8.7 KiB
Markdown
### 测试翻译
|
||
|
||
您需要将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`。 |