主题本地化：WordPress 主题翻译完全指南

发布于 作者:

每一个优秀的 WordPress 主题，都应该具备走向的能力。而本地化（Localization）就是赋予主题这种能力的关键一步。简单来说，一个完成了本地化的主题，可以根据网站后台设置的语言，自动切换并显示对应的翻译文本，让使用不同语言的用户都能获得良好的体验。这不仅仅是一个技术过程，更是一种让作品触达更广泛受众的思维方式。本文将带你梳理 WordPress 经典主题本地化的核心概念、文件类型以及基础的操作流程，帮助你理解如何让自己的主题“会说”多国语言。

理解两个关键概念：国际化与本地化

在 WordPress 主题开发中，有两个词经常一起出现：国际化（Internationalization） 和 本地化（Localization）。它们虽然紧密相关，但分工明确。

  • 国际化 (i18n)：这是指开发者在编写主题代码时，就为后续的翻译工作做好准备。比如，不直接在 HTML 里写死文本，而是使用 WordPress 提供的特定函数来包裹所有需要翻译的字符串。这一步是“打地基”，不需要懂外语，只需要懂代码规范。这个术语常被简写为 i18n，因为“Internationalization”这个词首字母 i 和尾字母 n 之间，正好有 18 个字母。
  • 本地化 (l10n)：这是指在国际化的基础上，将主题中的文本实际翻译成某一种具体的语言（比如中文、法语、阿拉伯语）。这一步通常由翻译人员或社区志愿者完成，不需要懂编程，但需要有很好的语言能力。本地化 的常见简写就是 l10n，同样的逻辑，首字母 l 和尾字母 n 之间隔着 10 个字母。

一个主题必须先完成国际化，才能被本地化。前者是开发者的责任，后者是翻译者的舞台。

本地化背后的三种核心文件

当我们在 WordPress 中谈论本地化时，离不开以下三种文件，它们构成了翻译工作的基础。你可以把它们理解为：一个模板和两种格式的成品文件。

1. POT 文件 (Portable Object Template)
这是一个模板文件，本身不包含任何翻译。它像是一个“待翻译文本清单”，由开发者在国际化过程中通过特定工具从主题的源代码中提取生成。翻译者拿到这个文件，就知道哪些文本需要被翻译。

2. PO 文件 (Portable Object)
这是翻译者真正要编辑的文件。它基于 POT 模板创建，包含了原始的待翻译文本以及翻译者输入的目标语言译文。这个文件是可读的文本格式，可以使用 Poedit 这类软件打开并编辑。

3. MO 文件 (Machine Object)
这是 PO 文件的“机器可读”版本，由 PO 文件编译生成。WordPress 在运行时不直接读取 PO 文件，而是读取体积更小、解析更快的 MO 文件来加载翻译。MO 文件通常存放在主题的 /languages/ 目录下。

经典主题本地化的基本流程

为了让你有更直观的理解，这里梳理一个经典的 WordPress 主题实现本地化的关键步骤。

一步：在主题中声明文本域

在主题的 style.css 文件头部，你需要通过 Text Domain 和 Domain Path 两个参数来声明文本域信息。文本域是一个的标识符，用来区分这个主题的翻译字符串。

css

/*
Theme Name: 我的自定义主题
Text Domain: my-theme
Domain Path: /languages
*/
  • Text Domain：必须与主题的文件夹名称保持一致，用于在代码中标识该主题的文本。
  • Domain Path：告诉 WordPress 去哪里寻找该主题的翻译文件（.mo 文件），通常是 /languages。

二步：在 functions.php 中加载翻译

为了让 WordPress 知道何时加载翻译文件，你需要在主题的 functions.php 文件中，挂载一个after_setup_theme 动作，并调用 load_theme_textdomain() 函数。

php

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

这段代码让 WordPress 在主题启动时，就去 /languages/ 文件夹下寻找并加载符合当前网站语言设置的 .mo 文件。

三步：使用翻译函数包裹文本

这是本地化核心的一步。在主题的任何 PHP 文件中，绝对不要直接写死需要输出的文本。你应该用 WordPress 提供的翻译函数将它们包裹起来。

  • __()：常用的函数。它只是返回翻译后的字符串，你需要配合 echo 输出。
  • _e()：与 __() 功能相同，但会直接打印（输出）翻译后的字符串。
  • _x()：用于需要根据上下文区分含义的单词或短语。比如英文单词“Post”，它可以表示文章（名词），也可以表示发布（动词），_x() 函数允许你为翻译者提供额外的注释信息。
  • _n()：用于处理单复数形式不同的语言。

代码演示：

php

// 不推荐的做法：直接输出
echo '欢迎访问我的网站';

// 正确的做法：使用翻译函数
_e( '欢迎访问我的网站', 'my-theme' ); // 直接打印

$welcome_message = __( '欢迎访问我的网站', 'my-theme' ); // 返回字符串，可用于赋值

// 处理需要上下文的词
echo _x( 'Post', 'noun: a piece of writing', 'my-theme' );

// 处理单复数
printf( _n( '找到 %s 篇文章', '找到 %s 篇文章', $count, 'my-theme' ), number_format_i18n( $count ) );

当你完成以上步骤后，你的主题就具备了“国际化”的基因。剩下的工作，就是生成 POT 模板，并交给翻译人员去创建对应语言的 PO 和 MO 文件了。

总结

本地化（l10n） 是 WordPress 主题走向多语言的一步，它依赖于开发者在代码中做好的国际化（i18n） 准备。整个过程可以概括为：在 style.css 中声明文本域，在 functions.php 中加载文本域，以及重要的——在所有需要显示文本的地方，使用 __()、_e() 等翻译函数来替代硬编码的字符串。遵循这些规范，你的主题就为全球用户打开了大门，而翻译者也可以通过 POT/PO/MO 这套标准的文件体系，轻松地完成后续的翻译工作。