WordPress 主题国际化（i18n）完全指南

发布于 作者:

WordPress 主题国际化，简单来说就是让你的主题能够被翻译成不同语言。全球有大量非英语用户使用 WordPress，如果你的主题代码中直接写死文字内容，翻译者必须修改源代码才能适配其他语言——这不仅低效，还容易出错。正确的做法是使用 WordPress 提供的翻译函数包裹所有文本，这样翻译者只需提供翻译文件，无需触碰核心代码。本文将用通俗易懂的方式，带你掌握主题国际化的核心概念和操作步骤，包括文本域的定义、翻译函数的用法、翻译文件的加载方式等。无论你是刚开始接触 WordPress 开发，还是想规范自己的主题代码，这篇指南都能帮你少走弯路。

一、什么是国际化？

国际化（Internationalization，缩写为 i18n，因为首字母 i 和尾字母 n 之间有 18 个字母）是让主题代码具备翻译能力的设计过程。它不是直接把文字翻译成其他语言，而是用特定函数包裹所有可见文字，为后续翻译工作铺好路。

为什么要做国际化？

WordPress 遍布全球，很多用户并不使用英语。作为开发者，你不可能为所有用户提供每种语言的翻译版本，但通过国际化的代码，三方翻译者可以轻松制作语言包，用户无需修改源码就能切换语言。

反面教材

php

<h1>设置页面</h1>

上面这段代码直接输出了中文标题。如果想把标题换成英文或日文，翻译者只能去改模板文件，维护起来非常痛苦。

正确示范

php

<h1><?php _e( '设置页面', 'my-theme' ); ?></h1>

使用 _e() 函数包裹文字后，翻译者通过翻译文件就能修改显示内容，完全不用碰 PHP 代码。

二、文本域（Text Domain）

文本域是 WordPress 用来区分不同主题或插件翻译来源的标识符。就像每家每户的门牌号，系统靠它知道某条翻译属于哪个主题。

命名规则

  • 只能使用小写字母和连字符（-），不要用下划线（_）
  • 如果你的主题在 WordPress.org 上架，文本域必须和主题目录的 URL 别名完全一致

举个例子：主题名称是“我的主题”，文件夹名为 my-theme，那么文本域就定为 my-theme。

三个必须使用文本域的地方

  1. style.css 文件头部：让 WordPress 在主题未启用时也能翻译描述信息
  2. 所有翻译函数的参数中：告诉系统这条文字属于哪个主题
  3. 加载翻译文件时：通过 load_theme_textdomain() 等函数指定文本域

style.css 头部示例

css

/*
Theme Name: 我的主题
Author: 张三
Text Domain: my-theme
Domain Path: /languages
*/

Domain Path 指定翻译文件存放的目录，默认为主题根目录下的 /languages 文件夹。如果文件放在别处，必须在这里声明，路径以斜杠开头。

三、常用的翻译函数

WordPress 提供了多个翻译函数，适用于不同场景。所有函数都必须带上文本域参数。

1. __() —— 返回翻译后的字符串

用于需要把翻译结果赋值给变量的情况。

php

$title = __( '文章分类', 'my-theme' );
echo $title;

2. _e() —— 直接输出翻译后的字符串

相当于 echo __() 的快捷方式。

php

_e( '阅读全文', 'my-theme' );

3. _n() —— 处理单复数形式

根据数量显示不同的文字，需要传入三个参数：单数形式、复数形式、计数值。

php

printf(
    _n( '找到 %s 篇文章', '找到 %s 篇文章', $count, 'my-theme' ),
    number_format_i18n( $count )
);

4. esc_html__() 和 esc_html_e()

带安全转义的版本，防止 XSS 攻击。当翻译内容中可能包含 HTML 标签时，优先使用这些函数。

php

echo esc_html__( '用户名', 'my-theme' );

四、加载翻译文件

翻译文件通常以 .po 和 .mo 格式存在。在主题的 functions.php 中通过 load_theme_textdomain() 加载。

推荐写法

php

function mytheme_load_textdomain() {
    load_theme_textdomain(
        'my-theme',
        get_template_directory() . '/languages'
    );
}
add_action( 'after_setup_theme', 'mytheme_load_textdomain' );

文件命名规则

  • 翻译文件放在主题目录下时，命名为 {语言代码}.mo（例如 zh_CN.mo）
  • 翻译文件放在 WordPress 全局语言目录（/wp-content/languages/themes/）时，命名为 {文本域}-{语言代码}.mo（例如 my-theme-zh_CN.mo）

注意：从 WordPress 4.6 开始，系统会自动检测 wp-content/languages 目录下的翻译包。如果你的主题在 WordPress.org 官方仓库中，翻译会自动同步，不需要额外加载。

五、语言包（Language Packs）

WordPress.org 上的主题会通过翻译平台自动收集各语种的翻译，用户安装主题后可以直接获得新语言包。想了解语言包的导入机制，可以查阅官方翻译手册。

六、总结

主题国际化并不复杂，核心就三条：

  1. 所有可见文字都用翻译函数包裹，永远不要硬编码输出
  2. 给主题定义一个的文本域，并在 style.css 和所有函数中保持一致
  3. 在 functions.php 中加载翻译文件，确保翻译能正常生效

把这些基础工作做好，你的主题就能被全球用户使用，翻译者也能轻松参与贡献。更重要的是，规范的国际化代码本身就是高质量主题的标志，对后续维护和扩展都大有裨益。