什么是国际化?

国际化是指开发主题的过程,以便可以轻松将其翻译成其他语言。国际化和通常缩写为 i18n(因为字母 i 和 n 之间有 18 个字母)。

为什么国际化很重要?

WordPress 在全球范围内使用广泛,特别是在英语不是主要语言的国家和地区。WordPress 插件中的字符串需要以特殊方式编码,以便可以轻松翻译成其他语言。作为开发者,您可能无法为所有用户提供本地化;然而,翻译人员可以在不修改源代码本身的情况下成功对主题进行本地化。

如何使您的主题国际化?

为了使主题的文本能够轻松被翻译,不应在主题中硬编码这些文本,而应通过 WordPress 的某个本地化函数作为参数传递。

以下示例除非翻译人员修改源代码,否则无法进行翻译,这效率不高。

<h1>设置页面</h1>

通过将字符串通过本地化函数传递,可以轻松解析并进行翻译。

<h1><?php _e( 'Settings Page' ); ?></h1>

WordPress 使用 gettext 库来在 PHP 中添加翻译。在 WordPress 中,您应该使用 WordPress 本地化函数,而不是原生的 PHP gettext 兼容的翻译函数。

文本域(Text Domain)

文本域是国际化函数中使用的第二个参数。文本域是一个唯一的标识符,允许 WordPress 区分所有已加载的翻译。主题和插件只需要定义文本域。

托管在 WordPress.org 上的主题的文本域必须与您的主题 URL 的 slug(短链接)匹配 (wordpress.org/themes/<slug>)。这是为了确保来自 translate.wordpress.org 的翻译能够正常工作。

文本域名必须使用连字符而不是下划线,并且必须是小写。例如,如果主题名称 My Theme 定义在 style.css 中或包含在名为 my-theme 的文件夹中,则文本域应为 my-theme。

文本域用于三个不同的地方:

  1. 在 style.css 主题头部
  2. 作为本地化函数中的参数
  3. 在使用 load_theme_textdomain() 或 load_child_theme_textdomain() 加载翻译时作为参数

style.css 主题头部

将文本域添加到 style.css 头部,以便即使未启用主题,也可以翻译如描述之类的主题元数据。使用的文本域应与加载文本域时使用的相同。

示例:

/*
* Theme Name: My Theme
* Author: Theme Author
* Text Domain: my-theme
*/
域路径(Domain Path)

当翻译保存在 languages 以外的目录时,需要指定域路径。这样 WordPress 就知道在主题未激活时应在哪里查找翻译。例如,如果 .mo 文件位于 languages 文件夹中,则 Domain Path 应为 /languages,并且必须写入第一个斜杠。默认值为主题的 languages 文件夹。

示例:

/*
* Theme Name: My Theme
* Author: Theme Author
* Text Domain: my-theme
* Domain Path: /languages
*/

为字符串添加文本域

为了使翻译正常工作,应将文本域作为参数添加到所有本地化函数中。

示例 1:

<?php __( 'Post' ); ?>

应改为

<?php __( 'Post', 'my-theme' ); ?>

示例 2:

<?php _e( 'Post' ); ?>

应改为

<?php _e( 'Post', 'my-theme' ); ?>

示例 3:

<?php _n( '%s post', '%s posts', $count ) ; ?>

应改为

<?php _n( '%s post', '%s posts', $count, 'my-theme' ); ?>

应将文本域作为字符串而不是变量传递给本地化函数。这允许解析工具区分不同的文本域。以下是不应该做的示例:

<?php __( 'Translate me.' , $text_domain ) ; ?>

加载翻译

WordPress 中的翻译保存在 .po 和 .mo 文件中,需要加载它们。可以通过使用函数 load_theme_textdomain() 或 load_child_theme_textdomain() 来加载它们。这将从您的主题的基础目录中加载 {locale}.mo,或者从位于 /wp-content/languages/themes/ 的 WordPress 主题语言文件夹中加载 {text-domain}-{locale}.mo。

自版本 4.6 起,WordPress 会自动检查 wp-content 中的语言目录以获取来自 translate.wordpress.org 的翻译。这意味着通过 translate.wordpress.org 进行翻译的插件不再需要调用 load_plugin_textdomain()。

如果您不想在您的插件中添加 load_plugin_textdomain() 调用,则应将 readme.txt 中的 Requires at least: 字段设置为 4.6。

要了解有关不同语言和国家代码的更多信息,请查看 语言列表。

注意

  • 如果将翻译添加到主题文件夹中,请将 MO 文件命名为 {locale}.mo(例如 de_DE.po & de_DE.mo)。
  • 如果将翻译添加到 WordPress 主题语言文件夹中,请将 MO 文件命名为 {text-domain}-{locale}.mo(例如 my-theme-de_DE.po & my-theme-de_DE.mo)。

示例:

<?php function my_theme_load_theme_textdomain() {
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );
}
add_action( 'after_setup_theme', 'my_theme_load_theme_textdomain' ) ; ?>

此函数最好在主题的 function.php 中运行。

语言包(Language Packs)

如果您对语言包以及导入到 translate.wordpress.org 的工作原理感兴趣,请阅读 Meta Handbook 关于翻译的页面。

使您的主题国际化

现在您的翻译已加载,您可以开始在主题中编写每个字符串时使用国际化和函数。

查看 Common APIs Handbook(通用 API 手册)上的Internationalization(国际化)页面以获取更多信息和最佳实践。