分析 WordPress `get_translation_file()` 函数的源码：如何根据本地化获取翻译文件路径。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷们，晚上好！我是你们的老朋友，今天咱们来聊聊WordPress里一个“低调奢华有内涵”的函数：get_translation_file()。别看它名字平平无奇，但它可是WordPress本地化（i18n）大厦的基石之一，负责根据当前的语言环境，把正确的翻译文件（通常是.mo文件）路径给揪出来。这家伙藏得挺深，一般的WordPress开发者可能很少直接用到它，但理解它的工作原理，能让你对WordPress的本地化机制有更深刻的认识。

1. 本地化：为什么要翻译？

咱们先来热个身，简单说说本地化。想象一下，你辛辛苦苦写了一个WordPress主题或插件，结果全世界的人都只能看懂你的母语，这多可惜！为了让你的作品能够被更多人使用，你需要把它翻译成不同的语言。这就是本地化（Localization，通常缩写为 l10n）要做的事情。

WordPress本身就支持本地化，它使用 GNU gettext 来实现这一功能。简单来说，gettext 的工作流程是这样的：

在代码中，开发者使用 __(), _e(), _x(), _n() 等函数来标记需要翻译的文本。
使用工具（如 Poedit）从代码中提取这些标记的文本，生成一个 .po 文件（Portable Object）。
翻译人员将 .po 文件中的文本翻译成目标语言，并保存成 .mo 文件（Machine Object）。.mo 文件是编译后的二进制文件，WordPress可以直接读取。
WordPress 根据当前的语言设置，加载对应的 .mo 文件，并将代码中标记的文本替换成翻译后的文本。

2. `get_translation_file()`：寻找翻译文件的侦察兵

OK，有了本地化的基础知识，我们就可以开始研究 get_translation_file() 函数了。这个函数的主要作用是：给定一个翻译文件的基名 (basename) 和目录，找到实际的 .mo 文件的完整路径。

让我们先来看看它的定义（为了方便理解，这里简化了一些代码）：

function get_translation_file( $domain, $mofile ) {
    global $l10n;

    $lang = get_locale(); // 获取当前的语言环境

    // 尝试不同的文件命名规则，查找 .mo 文件
    $locations = array(
        WP_LANG_DIR . '/' . $mofile, // 1. WP_LANG_DIR/basename.mo
        WP_LANG_DIR . '/' . $lang . '/' . $mofile, // 2. WP_LANG_DIR/lang/basename.mo
        WP_LANG_DIR . '/' . $lang . '-' . get_bloginfo( 'version' ) . '/' . $mofile, // 3. WP_LANG_DIR/lang-version/basename.mo
        // ... 还有一些其他的查找路径
    );

    foreach ( $locations as $location ) {
        if ( file_exists( $location ) ) {
            return $location; // 找到就返回
        }
    }

    return false; // 没找到就返回 false
}

这个函数接收两个参数：

$domain: 翻译文件的文本域 (text domain)。文本域是一个用于区分不同翻译文件的字符串，通常是主题或插件的名称。
$mofile: 翻译文件的基名 (basename)。比如，如果翻译文件是 my-theme-zh_CN.mo，那么 $mofile 就是 my-theme-zh_CN.mo。

工作流程分析：

获取当前语言环境： 函数首先使用 get_locale() 获取当前的语言环境。语言环境是一个字符串，用于标识用户的语言和地区，比如 zh_CN (简体中文)，en_US (美国英语) 等。
构建可能的 .mo 文件路径： 接下来，函数会构建一个可能的 .mo 文件路径的数组 $locations。这个数组包含了WordPress默认会查找翻译文件的几个位置。注意，查找顺序非常重要，WordPress会按照这个顺序依次查找，直到找到文件为止。
循环查找： 函数循环遍历 $locations 数组，使用 file_exists() 函数检查每个路径是否存在对应的文件。
找到就返回： 如果找到了 .mo 文件，函数立即返回它的完整路径。
没找到就返回 false： 如果循环结束后仍然没有找到 .mo 文件，函数返回 false。

重点解释：$locations 数组

$locations 数组是 get_translation_file() 函数的核心。它定义了WordPress查找翻译文件的优先级顺序。下面我们详细分析几种常见的查找路径：

序号	路径	说明
1	`WP_LANG_DIR . '/' . $mofile`	`WP_LANG_DIR` 是 WordPress 语言目录的路径，通常是 `wp-content/languages/`。这种路径表示直接将 .mo 文件放在语言目录下，不区分语言环境。不推荐使用，容易造成文件管理混乱。
2	`WP_LANG_DIR . '/' . $lang . '/' . $mofile`	`$lang` 是当前的语言环境，比如 `zh_CN`。这种路径表示将 .mo 文件放在语言目录下的一个子目录中，子目录的名称与语言环境相同。这是推荐的做法，方便管理不同语言的翻译文件。
3	`WP_LANG_DIR . '/' . $lang . '-' . get_bloginfo( 'version' ) . '/' . $mofile`	`get_bloginfo( 'version' )` 获取当前的 WordPress 版本号。这种路径表示将 .mo 文件放在一个与语言环境和 WordPress 版本号相关的子目录中。这种做法是为了兼容不同版本的 WordPress，但现在已经很少使用了。
4	`WPINC . '/languages/' . $mofile`	`WPINC` 是 WordPress 核心文件目录的路径，通常是 `wp-includes/`。这种路径指向 WordPress 核心的翻译文件。
5	`WP_LANG_DIR . '/plugins/' . $mofile`	插件的翻译文件路径
6	`WP_LANG_DIR . '/themes/' . $mofile`	主题的翻译文件路径

举个例子：

假设当前语言环境是 zh_CN，WP_LANG_DIR 是 /var/www/wordpress/wp-content/languages/，$mofile 是 my-plugin-zh_CN.mo。那么 get_translation_file() 函数会按照以下顺序查找 .mo 文件：

/var/www/wordpress/wp-content/languages/my-plugin-zh_CN.mo
/var/www/wordpress/wp-content/languages/zh_CN/my-plugin-zh_CN.mo
/var/www/wordpress/wp-content/languages/zh_CN-6.2/my-plugin-zh_CN.mo (假设 WordPress 版本是 6.2)
…

3. 如何使用 `get_translation_file()`？

虽然我们很少直接调用 get_translation_file() 函数，但了解它的工作原理可以帮助我们更好地理解 WordPress 的本地化机制。例如，我们可以利用它来调试翻译问题。

假设我们发现某个插件的翻译没有生效，我们可以尝试使用 get_translation_file() 函数来检查 .mo 文件是否被正确加载：

$plugin_text_domain = 'my-plugin';
$mofile = $plugin_text_domain . '-' . get_locale() . '.mo';

$mofile_path = get_translation_file( $plugin_text_domain, $mofile );

if ( $mofile_path ) {
    echo '翻译文件已加载：' . $mofile_path;
} else {
    echo '翻译文件未找到！';
}

这段代码首先定义了插件的文本域和 .mo 文件的基名。然后，它调用 get_translation_file() 函数来查找 .mo 文件。如果找到了 .mo 文件，就输出它的路径；否则，就输出一个错误信息。

4. 与 `load_textdomain()` 的关系

get_translation_file() 函数通常与 load_textdomain() 函数一起使用。 load_textdomain() 函数负责加载 .mo 文件，并将翻译应用到代码中。

function load_textdomain( $domain, $mofile ) {
    global $l10n, $wp_filesystem;

    $mofile = validate_file( $mofile );
    if ( ! $mofile ) {
        return false;
    }

    $mofile = apply_filters( 'load_textdomain_mofile', $mofile, $domain );

    // 判断是否已经加载
    if ( isset( $l10n[ $domain ] ) && ( $l10n[ $domain ]->mofile == $mofile ) ) {
        return true;
    }

    $mofile_global = WP_LANG_DIR . '/' . $mofile;

    // 获取 .mo 文件的完整路径
    $mofile = get_translation_file( $domain, $mofile );

    if ( ! file_exists( $mofile ) ) {
        return false;
    }

    // ... 加载 .mo 文件的代码
}

可以看到，load_textdomain() 函数内部会调用 get_translation_file() 函数来获取 .mo 文件的完整路径。然后，它会将 .mo 文件加载到内存中，并将翻译应用到代码中。

总结一下：

get_translation_file() 负责找到正确的 .mo 文件。
load_textdomain() 负责加载 .mo 文件并应用翻译。

它们就像一对好基友，一个负责找吃的，一个负责吃。

5. 自定义翻译文件路径

WordPress 提供了几个过滤器 (filters) 让我们能够自定义翻译文件的路径。最常用的过滤器是 load_textdomain_mofile。

例如，我们可以使用 load_textdomain_mofile 过滤器来将所有的翻译文件都放在一个特定的目录下：

add_filter( 'load_textdomain_mofile', 'my_custom_mofile_path', 10, 2 );

function my_custom_mofile_path( $mofile, $domain ) {
    $custom_path = WP_CONTENT_DIR . '/my-translations/' . $mofile;
    if ( file_exists( $custom_path ) ) {
        return $custom_path;
    }
    return $mofile;
}

这段代码会将所有的 .mo 文件都放在 wp-content/my-translations/ 目录下。注意，这个过滤器接收两个参数：

$mofile: 原始的 .mo 文件路径。
$domain: 翻译文件的文本域。

我们可以在过滤器函数中修改 $mofile 的值，来指定新的 .mo 文件路径。如果新的路径存在对应的文件，就返回新的路径；否则，就返回原始的路径，让 WordPress 按照默认的方式查找 .mo 文件。

6. 一些使用技巧和注意事项

命名规范： 翻译文件的命名应该遵循一定的规范。通常的命名规则是 text-domain-locale.mo，其中 text-domain 是文本域，locale 是语言环境。例如，my-plugin-zh_CN.mo。
文本域： 文本域应该与主题或插件的名称保持一致。这可以避免不同主题或插件之间的翻译冲突。
语言环境： 语言环境应该与 WordPress 的语言设置保持一致。你可以在 WordPress 后台的 "设置" -> "常规" 页面中修改语言设置。
缓存： WordPress 会缓存翻译文件。如果你修改了 .mo 文件，你需要清除缓存才能看到效果。你可以使用一些缓存插件来清除缓存，或者直接删除 wp-content/languages/ 目录下的缓存文件。
安全： 确保你的翻译文件来自可信的来源。恶意构造的翻译文件可能包含恶意代码，导致安全问题。

7. 总结

get_translation_file() 函数是 WordPress 本地化机制中一个重要的组成部分。它负责根据当前的语言环境，找到正确的 .mo 文件。了解它的工作原理，可以帮助我们更好地理解 WordPress 的本地化机制，并解决翻译问题。虽然我们很少直接调用它，但理解它的内部逻辑，能让你在处理多语言网站的时候更加得心应手。

好了，今天的讲座就到这里。希望大家有所收获！记住，编程就像谈恋爱，要多了解对方，才能更好地相处。我们下次再见！

1. 本地化：为什么要翻译？

2. get_translation_file()：寻找翻译文件的侦察兵

3. 如何使用 get_translation_file()？

4. 与 load_textdomain() 的关系