进阶 yourls.org 2026-11-19 17:39:56 · 2 阅读
第12章 国际化(Internationalisation)
Internationalisation
本页说明如何让代码具备被译制的基础,以便译者生成目标语言的翻译文件。若需了解翻译的基本概念,请同时参阅语言指南。
i18n?
i18n 是国际化的缩写,指将代码改造为可翻译状态的过程。之所以叫 "i18n",是因为首尾字母 i 和 n 之间恰好有 18 个字母。就 YOURLS 而言,这意味着以特定方式标记需要翻译的字符串。
硬编码与可翻译字符串
在 PHP 中,回显或返回字符串的常规方式是:
```php
echo "This is a message.";
return "another string";
```
在此例中,字符串是硬编码的,除非直接修改 PHP 文件,否则无法更改,这显然不够实用。
YOURLS 使用一组函数来标记字符串,指示它们在存在翻译文件时应当被翻译。
标记待翻译字符串
其基本原则如下:
`yourls_i18n_function( $string, $textdomain )`
其中:
* `yourls_i18n_function` 是某个 i18n 函数,详见下文。
* `$string` 是待翻译的字符串。
* `$textdomain` 是唯一的标识符(即“文本域”),将在整个项目中通用。请确保它是唯一的名称,例如基于你的插件名生成。
上述示例将变为:
```php
// 回显字符串
yourls_e( 'This is a message', 'john-plugin' );
// 返回字符串
$message = yourls__( 'another string', 'john-plugin' );
```
这将产生两个效果:
1. 如果找到翻译文件,i18n 函数返回翻译后的字符串;否则返回原始字符串。
2. 这些函数同时标记字符串为可翻译:借助 Poedit 等工具(见下文),可以生成包含这些字符串的 PO 或 POT 文件,供译者制作翻译文件。
加载你的文本域
选择一个唯一的名称,最好与项目名称相关。例如,如果你正在编写名为 "Funny Redirection" 的插件,域名可以是 `funny-redirection`。
你的代码中必须包含以下函数调用:
`yourls_load_custom_textdomain( $domain, $path_to_translation_files );`
例如,在你的插件中可能如下:
```php
// 在所有插件加载后触发
yourls_add_action( 'plugins_loaded', 'funny_redirection_load_textdomain' );
// 加载自定义文本域
function funny_redirection_load_textdomain() {
yourls_load_custom_textdomain( 'funny-redirection', dirname( __FILE__ ) . '/translations' );
}
```
这会让 YOURLS 在插件文件夹的 translations 目录中查找翻译文件。
翻译文件名必须遵循以下格式:域名-语言区域,例如 funny_redirection-pt_BR.mo
i18n 函数
YOURLS 的 i18n 函数位于 includes/functions-i18n.php,主要函数如下:
yourls__( $string, $domain )
返回翻译后的字符串
yourls_e( $string, $domain )
输出翻译后的字符串
yourls_n( $single, $plural, $number, $domain )
根据数量返回复数或单数形式。示例:
$msg = yourls_n( '1 tooth', '%s teeth', $number, 'funny-redirection' );
转义函数:
yourls_esc_html__( $string, $domain )
获取 $string 的翻译,并对其进行转义,以便安全地输出到 HTML 中
yourls_esc_attr__( $string, $domain )
返回翻译后的字符串,并转义后用于属性中(如 title="")
另外还有对应的 xxxx_e() 函数,用于直接输出而不是返回。
还有一些更复杂的函数,做基础功能时可能用不上,不过读一读 includes/functions-i18n.php 的源码,一定会让你受益匪浅 😊
占位符
待翻译的字符串不能包含动态内容。例如,
这样写可以正常工作:echo "We have $count short URL";
但这样不行:yourls_e( "We have $count short URL", "myplugin" );
在解析代码生成 PO 文件时,PO 生成器会把 "We have $count short URL" 标记为可翻译字符串。但程序实际运行时,yourls_e() 接收到的参数是类似 "We have 1337 short URL" 这样的字符串:YOURLS 找不到与之匹配的翻译,就会原样返回未翻译的字符串。
解决办法是使用 printf()(输出)和 sprintf()(返回)函数。
针对短链接数量问题,正确的写法如下:
printf( yourls__( "We have %s short URL", "myplugin" ), $count );
生成 POT 文件 当所有代码准备就绪并可以进行翻译时,生成 POT 文件。你需要配置软件(例如 PoEdit),使其识别 YOURLS 中使用的这些 i18n 函数: yourls__ yourls_e yourls_s yourls_se yourls_esc_attr__ yourls_esc_html__ yourls_x yourls_ex yourls_esc_attr_x yourls_esc_html_x yourls_n:1,2 yourls_nx:1,2 yourls_n_noop:1,2 yourls_nx_noop:1,2 还要配置解析器,让它包含给译者的注释。在 PoEdit 中:文件 → 偏好设置 → 解析器 → PHP:编辑并在“Parser 命令”中添加参数 --add-comments=/ 你在网上可以找到大量关于如何使用 PoEdit 的指南。同时,也请查阅官方的 YOURLS.pot 文件。 找几位译者开始工作 你的工作现在已准备好进行翻译。请一些日语 / 巴西葡语 / 捷克语朋友创建翻译文件,并让你的代码附带所有这些翻译文件一起发布 😊
生成 POT 文件 当所有代码准备就绪并可以进行翻译时,生成 POT 文件。你需要配置软件(例如 PoEdit),使其识别 YOURLS 中使用的这些 i18n 函数: yourls__ yourls_e yourls_s yourls_se yourls_esc_attr__ yourls_esc_html__ yourls_x yourls_ex yourls_esc_attr_x yourls_esc_html_x yourls_n:1,2 yourls_nx:1,2 yourls_n_noop:1,2 yourls_nx_noop:1,2 还要配置解析器,让它包含给译者的注释。在 PoEdit 中:文件 → 偏好设置 → 解析器 → PHP:编辑并在“Parser 命令”中添加参数 --add-comments=/ 你在网上可以找到大量关于如何使用 PoEdit 的指南。同时,也请查阅官方的 YOURLS.pot 文件。 找几位译者开始工作 你的工作现在已准备好进行翻译。请一些日语 / 巴西葡语 / 捷克语朋友创建翻译文件,并让你的代码附带所有这些翻译文件一起发布 😊