深入理解 WordPress `load_theme_textdomain()` 函数的源码：如何为主题加载翻译文件。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷们，晚上好！今天咱们来聊聊WordPress主题本地化的秘密武器：load_theme_textdomain() 函数。别怕，虽然听着高大上，但其实它就是个勤勤恳恳的搬运工，负责把那些翻译好的语言包搬到你的主题里，让你的用户能看到亲切的母语界面。

准备好了吗？咱们开车了！

一、什么是Text Domain？为什么要它？

在深入 load_theme_textdomain() 之前，咱们先搞清楚一个概念：Text Domain。简单来说，Text Domain 就是一个字符串，用来唯一标识你的主题或插件。它就像你家的门牌号，方便WordPress找到属于你的翻译文件。

想象一下，如果没有Text Domain，所有主题和插件的翻译文件都混在一起，那会乱成什么样？ WordPress就不知道哪个翻译对应哪个主题了，肯定会报错。

Text Domain有以下好处：

防止冲突： 不同的主题/插件可以用相同的翻译键（key），只要Text Domain不同，就不会冲突。比如，两个主题都有一个按钮叫做 "Submit"，但它们的Text Domain不同，WordPress就能正确地加载对应的翻译。
组织翻译文件： Text Domain 帮助 WordPress 组织翻译文件，使得加载和管理翻译变得更加容易。
代码清晰： 在代码中使用 Text Domain 可以让代码更易读和维护。

通常，我们会把主题的 Text Domain 设置成主题的 slug (主题目录名)。比如，你的主题目录是 my-awesome-theme，那么你的 Text Domain 就可以是 my-awesome-theme。

二、load_theme_textdomain()：本地化的核心

load_theme_textdomain() 函数是 WordPress 提供的一个核心函数，专门用于加载主题的翻译文件。它的作用是：

找到主题的翻译文件（通常是 .mo 文件）。
加载翻译文件，并将翻译后的字符串与代码中的 Text Domain 关联起来。
这样，当你使用翻译函数 (比如 __(), _e(), _x(), _n()) 时，WordPress 就能找到对应的翻译，并显示出来。

三、load_theme_textdomain() 函数的语法和参数

咱们先来看看 load_theme_textdomain() 函数的语法：

<?php
load_theme_textdomain( string $domain, string|bool $path = false );
?>

$domain (string, required): Text Domain。也就是你主题的门牌号。必须是唯一的，建议使用主题的 slug。
$path (string|bool, optional): 翻译文件所在的目录。默认是 false，表示翻译文件在主题的根目录下的 languages 目录中。你可以指定一个相对于主题根目录的路径。

四、load_theme_textdomain() 函数的源码解析 (简化版)

为了方便理解，咱们来简化一下 load_theme_textdomain() 的源码 (基于 WordPress 6.x):

function load_theme_textdomain( $domain, $path = false ) {
    global $l10n; // 全局翻译数组

    $locale = get_locale(); // 获取当前站点语言

    $mofile = get_template_directory() . '/languages/' . $domain . '-' . $locale . '.mo'; // 默认的翻译文件路径

    if ( ! empty( $path ) ) {
        $mofile = get_template_directory() . '/' . $path . '/' . $domain . '-' . $locale . '.mo'; // 自定义路径
    }

    if ( file_exists( $mofile ) ) { // 检查文件是否存在
        if ( is_readable( $mofile ) ) { // 检查文件是否可读
            $l10n[ $domain ] = new MO(); // 创建一个 MO 对象 (MO = Machine Object)
            $l10n[ $domain ]->import_from_file( $mofile ); // 从 .mo 文件导入翻译
            return true; // 加载成功
        }
    }
    return false; // 加载失败
}

逐行解读：

global $l10n;: 声明全局变量 $l10n。这个变量是一个数组，用来存储所有已加载的翻译。它的键是 Text Domain，值是对应的 MO 对象。
$locale = get_locale();: 获取当前站点的语言设置。比如，如果你的站点语言是中文（中国），那么 $locale 的值就是 zh_CN。
$mofile = get_template_directory() . '/languages/' . $domain . '-' . $locale . '.mo';: 构造翻译文件的默认路径。 get_template_directory() 返回当前主题的根目录。所以，默认情况下，WordPress 会在主题根目录下的 languages 目录中查找翻译文件，文件名格式为 [text-domain]-[locale].mo。比如，如果 Text Domain 是 my-awesome-theme，站点语言是 zh_CN，那么默认的翻译文件路径就是 [主题根目录]/languages/my-awesome-theme-zh_CN.mo。
if ( ! empty( $path ) ) { ... }: 如果 $path 参数不为空，则使用自定义的翻译文件路径。这样可以让你把翻译文件放在任何你喜欢的地方。
if ( file_exists( $mofile ) ) { ... }: 检查翻译文件是否存在。
if ( is_readable( $mofile ) ) { ... }: 检查翻译文件是否可读。
$l10n[ $domain ] = new MO();: 创建一个 MO 对象。 MO 是 "Machine Object" 的缩写，它是一个专门用来处理 .mo 文件的类。
$l10n[ $domain ]->import_from_file( $mofile );: 从 .mo 文件导入翻译。 import_from_file() 方法会读取 .mo 文件中的翻译数据，并将其存储在 MO 对象中。
return true;: 加载成功，返回 true。
return false;: 加载失败，返回 false。

五、如何使用 load_theme_textdomain() 函数

通常，你会在主题的 functions.php 文件中调用 load_theme_textdomain() 函数。最佳实践是把它放在 after_setup_theme 钩子上，确保主题的基本功能已经加载完毕。

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

代码解释：

my_awesome_theme_setup(): 这是你自定义的函数，用来加载主题的翻译文件。
load_theme_textdomain( 'my-awesome-theme', get_template_directory() . '/languages' );: 调用 load_theme_textdomain() 函数，加载 Text Domain 为 my-awesome-theme 的翻译文件。第二个参数指定了翻译文件所在的目录是主题根目录下的 languages 目录。
add_action( 'after_setup_theme', 'my_awesome_theme_setup' );: 将 my_awesome_theme_setup() 函数绑定到 after_setup_theme 钩子上。这意味着当 WordPress 完成主题的基本设置后，就会自动调用 my_awesome_theme_setup() 函数。

六、翻译函数：让你的主题说多种语言

光加载了翻译文件还不够，你还需要使用翻译函数来标记需要翻译的字符串。 WordPress 提供了几个常用的翻译函数：

__(): 返回翻译后的字符串。
_e(): 输出翻译后的字符串。
_x(): 带上下文的翻译。当同一个词在不同的语境下有不同的含义时，可以使用这个函数。
_n(): 处理单复数形式。

示例：

<?php
// 使用 __() 函数
$translated_string = __( 'Hello, world!', 'my-awesome-theme' );
echo $translated_string; // 输出翻译后的 "Hello, world!"

// 使用 _e() 函数
_e( 'Welcome to my website!', 'my-awesome-theme' ); // 直接输出翻译后的 "Welcome to my website!"

// 使用 _x() 函数
$translated_string = _x( 'Post', 'noun', 'my-awesome-theme' ); // "Post" 作为名词时的翻译
echo $translated_string;

// 使用 _n() 函数
$comment_count = 5;
$translated_string = sprintf( _n( '%s comment', '%s comments', $comment_count, 'my-awesome-theme' ), number_format_i18n( $comment_count ) );
echo $translated_string; // 输出 "5 comments"
?>

代码解释：

每个翻译函数都接受两个参数：需要翻译的字符串和 Text Domain。
WordPress 会根据当前的站点语言和 Text Domain，在已加载的翻译文件中查找对应的翻译。
如果找到了翻译，就返回或输出翻译后的字符串。如果没有找到，就返回或输出原始字符串。

七、创建和管理翻译文件

创建 .pot 文件 (Portable Object Template): .pot 文件是一个模板文件，包含了所有需要翻译的字符串。你可以使用工具 (比如 Poedit, Loco Translate) 从你的主题代码中提取这些字符串，并生成 .pot 文件。
- 使用 Poedit: 打开 Poedit，选择 "文件" -> "新建自 POT 文件"。然后，选择你的主题的 .pot 文件。 Poedit 会创建一个新的 .po 文件。
- 使用 WP-CLI: 如果你喜欢命令行，可以使用 WP-CLI 来生成 .pot 文件：
```
wp i18n make-pot . languages/my-awesome-theme.pot --slug=my-awesome-theme
```
  这条命令会在你的主题根目录下的 languages 目录中创建一个名为 my-awesome-theme.pot 的文件。
创建 .po 文件 (Portable Object): .po 文件是实际的翻译文件。你可以在 .po 文件中填写每个字符串的翻译。
- 使用 Poedit: 在 Poedit 中打开 .pot 文件后，选择 "文件" -> "另存为…"，然后将文件保存为 [text-domain]-[locale].po。比如，如果你的 Text Domain 是 my-awesome-theme，站点语言是 zh_CN，那么你应该将文件保存为 my-awesome-theme-zh_CN.po。
创建 .mo 文件 (Machine Object): .mo 文件是机器可读的二进制文件。 WordPress 使用 .mo 文件来加载翻译。
- 使用 Poedit: 在 Poedit 中保存 .po 文件时，Poedit 会自动生成对应的 .mo 文件。
- 使用 WP-CLI: 可以使用 WP-CLI 将 .po 文件编译成 .mo 文件：
```
wp i18n compile-mo languages/my-awesome-theme-zh_CN.po
```
  这条命令会将 my-awesome-theme-zh_CN.po 文件编译成 my-awesome-theme-zh_CN.mo 文件。
将 .po 和 .mo 文件放在 languages 目录中： 将翻译好的 .po 和 .mo 文件放在主题根目录下的 languages 目录中 (或者你在 load_theme_textdomain() 函数中指定的目录)。

表格总结：文件类型和作用

文件类型	后缀名	作用
POT	`.pot`	模板文件，包含了所有需要翻译的字符串。用于提取主题/插件中的待翻译文本，作为翻译的基础。
PO	`.po`	翻译文件，包含了每个字符串的翻译。用户可以在 `.po` 文件中编辑翻译，针对不同的语言创建不同的 `.po` 文件。
MO	`.mo`	机器可读的二进制文件，WordPress 使用 `.mo` 文件来加载翻译。由 `.po` 文件编译而来，优化了加载速度。

八、常见问题和注意事项

Text Domain 必须唯一： 确保你的 Text Domain 在整个 WordPress 站点中是唯一的。否则，可能会导致翻译冲突。
翻译文件命名规范： 翻译文件必须按照 [text-domain]-[locale].mo 的格式命名。比如，my-awesome-theme-zh_CN.mo。
缓存问题： 当你修改了翻译文件后，可能需要清除 WordPress 的缓存才能看到效果。
使用合适的翻译工具： 推荐使用 Poedit 或 Loco Translate 等专业的翻译工具。这些工具可以帮助你更轻松地管理翻译文件。
保持翻译的一致性： 在翻译过程中，尽量保持用词和风格的一致性。可以使用术语表来帮助你保持一致性。
测试翻译： 在发布主题/插件之前，务必测试翻译是否正确。可以切换 WordPress 的语言设置来测试不同语言的翻译效果。

九、总结

load_theme_textdomain() 函数是 WordPress 主题本地化的关键。通过它，你可以轻松地加载翻译文件，让你的主题支持多种语言。希望今天的讲解能够帮助你更好地理解 load_theme_textdomain() 函数的原理和使用方法。

记住，本地化不仅仅是翻译字符串，更重要的是为你的用户提供更好的体验。一个好的本地化策略可以帮助你吸引更多的用户，提高你的主题/插件的受欢迎程度。

好了，今天的讲座就到这里。感谢各位的观看！咱们下期再见！

发表回复 取消回复

发表回复取消回复