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

各位码农大家好，我是今天的主讲人，咱们今天来聊聊 WordPress 里一个有点低调但又特别重要的函数：load_theme_textdomain()，它负责让你的主题说多国语言，也就是加载翻译文件。

一、开场白：为什么我们需要翻译？

想象一下，你辛辛苦苦开发了一个主题，功能强大，界面美观，结果只有英语用户能看懂。是不是有点可惜？为了让更多人能用上你的主题，支持多语言就显得尤为重要了。而 load_theme_textdomain() 就是负责这项工作的关键函数。

二、load_theme_textdomain() 的基本用法

这个函数的作用是加载主题的翻译文件，让主题中用 __()、_e() 等翻译函数包裹的文本显示成用户选择的语言。

它的基本用法是这样的：

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

解释一下：

my-theme: 这是你的主题的文本域名 (text domain)，相当于你主题的“身份证”，用于区分不同主题的翻译。
get_template_directory() . '/languages': 这是翻译文件存放的目录，一般放在主题根目录下的 languages 文件夹里。

这段代码通常放在主题的 functions.php 文件中，并且用 after_setup_theme 钩子来执行，确保 WordPress 完成基本设置后再加载翻译。

三、深入源码：load_theme_textdomain() 的内部机制

光会用还不够，让我们扒开 load_theme_textdomain() 的源码，看看它到底做了些什么。以下是简化后的源码结构 (基于 WordPress 6.x)：

function load_theme_textdomain( $domain, $path = false ) {
    global $l10n, $wp_locale_directories;

    $locale = get_locale();

    // 1. 如果已经加载过，直接返回
    if ( isset( $l10n[ $domain ] ) && ! empty( $l10n[ $domain ] ) ) {
        return true;
    }

    // 2. 确定翻译文件路径
    if ( false === $path ) {
        $path = get_template_directory() . '/languages'; // 默认路径
    }

    // 3. 构建可能的翻译文件名
    $mofile = sprintf( '%1$s-%2$s.mo', $domain, $locale );

    // 4. 查找翻译文件
    $mofile_global = WP_LANG_DIR . '/themes/' . $mofile;
    $mofile_local  = $path . '/' . $mofile;

    // 5. 优先加载全局翻译文件 (WP_LANG_DIR/themes/)
    if ( file_exists( $mofile_global ) ) {
        $loaded = load_textdomain( $domain, $mofile_global );
    } elseif ( file_exists( $mofile_local ) ) {
        // 6. 如果全局文件不存在，加载主题目录下的翻译文件
        $loaded = load_textdomain( $domain, $mofile_local );
    } else {
        $loaded = false; // 7. 如果文件不存在，加载失败
    }

    return $loaded;
}

我们来一步一步分析：

检查是否已加载： 函数首先检查 $l10n 全局变量，这是一个存储已加载的文本域的数组。如果 $domain 对应的文本域已经存在，说明翻译文件已经加载过了，直接返回 true，避免重复加载。
确定翻译文件路径： 如果没有指定 $path，函数会使用 get_template_directory() . '/languages' 作为默认路径。
构建翻译文件名： 根据文本域名 $domain 和当前用户的语言环境 $locale，构建翻译文件的名字，例如 my-theme-zh_CN.mo。
查找翻译文件： 函数会查找两个地方的翻译文件：
- WP_LANG_DIR/themes/: 这是全局翻译文件目录，通常是 /wp-content/languages/themes/。
- $path: 这是主题目录下的 languages 文件夹。
优先加载全局翻译文件： 函数优先加载全局翻译文件。这样做的目的是允许用户覆盖主题自带的翻译，方便定制。
加载主题目录下的翻译文件： 如果全局翻译文件不存在，函数会加载主题目录下的翻译文件。
加载失败： 如果两个地方的翻译文件都不存在，函数返回 false，表示加载失败。

四、load_textdomain()：幕后英雄

在 load_theme_textdomain() 中，真正负责加载翻译文件的是 load_textdomain() 函数。让我们也简单看看它的源码：

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

    // 1. 安全检查：确保文件存在且可读
    if ( ! is_readable( $mofile ) ) {
        return false;
    }

    // 2. 实例化 MO 对象
    $mo = new MO();

    // 3. 加载 .mo 文件
    if ( ! $mo->import_from_file( $mofile ) ) {
        return false;
    }

    // 4. 将 MO 对象存储到 $l10n 数组中
    if ( isset( $l10n[ $domain ] ) ) {
        $mo->merge_with( $l10n[ $domain ] );
    }

    $l10n[ $domain ] = &$mo;

    return true;
}

关键步骤：

安全检查： 确保 $mofile 指向的文件存在且可读。
实例化 MO 对象： MO 类是 WordPress 用来处理 .mo 文件的类。
加载 .mo 文件： 调用 $mo->import_from_file() 方法，从 .mo 文件中读取翻译数据。
存储到 $l10n 数组： 将 MO 对象存储到 $l10n 全局变量中，方便后续使用。如果 $l10n 中已经存在 $domain 对应的 MO 对象，则进行合并。

五、.po 和 .mo 文件：翻译的基石

.po 和 .mo 文件是 WordPress 翻译的核心。

.po (Portable Object) 文件： 这是人类可读的文本文件，包含了原文和对应的翻译。
.mo (Machine Object) 文件： 这是机器可读的二进制文件，是 .po 文件编译后的结果，WordPress 使用 .mo 文件来快速查找翻译。

你需要先创建 .po 文件，然后使用 Poedit 等工具将其编译成 .mo 文件。

六、文本域名 (Text Domain)：主题的身份证

文本域名是主题的唯一标识符，用于区分不同主题的翻译。选择一个合适的文本域名非常重要。

命名规则： 建议使用主题的 Slug 作为文本域名，例如 my-awesome-theme。
一致性： 在整个主题中，必须使用相同的文本域名。

七、翻译函数：让文本动起来

WordPress 提供了几个常用的翻译函数：

函数	作用	示例
`__()`	返回翻译后的文本	`<?php echo __( 'Hello, world!', 'my-theme' ); ?>`
`_e()`	输出翻译后的文本	`<?php _e( 'Hello, world!', 'my-theme' ); ?>`
`_x()`	根据上下文返回翻译后的文本，用于区分相同原文在不同语境下的翻译	`<?php echo _x( 'Post', 'noun', 'my-theme' ); ?>`
`_ex()`	根据上下文输出翻译后的文本	`<?php _ex( 'Post', 'noun', 'my-theme' ); ?>`
`_n()`	根据数量返回单数或复数形式的翻译，用于处理不同数量下的文本显示	`<?php echo _n( '%s comment', '%s comments', $count, 'my-theme' ); ?>`
`_nx()`	根据数量和上下文返回单数或复数形式的翻译	`<?php echo _nx( '%s book', '%s books', $count, 'noun', 'my-theme' ); ?>`
`esc_attr__()`	返回经过 HTML 属性转义后的翻译文本，用于 HTML 属性中	`<input type="text" value="<?php echo esc_attr__( 'Search', 'my-theme' ); ?>">`
`esc_html__()`	返回经过 HTML 转义后的翻译文本，用于 HTML 内容中	`<h1><?php echo esc_html__( 'Welcome', 'my-theme' ); ?></h1>`

使用这些函数时，请务必传入文本域名，确保 WordPress 能够找到正确的翻译。

八、最佳实践：让翻译更轻松

使用 Poedit： Poedit 是一款强大的翻译工具，可以帮助你创建、编辑和编译 .po 和 .mo 文件。
保持代码清晰： 尽量将文本字符串放在单独的变量中，方便翻译。
注释： 在代码中添加注释，说明文本的含义和上下文，方便翻译人员理解。
测试： 确保在不同语言环境下测试你的主题，确保翻译正确显示。
使用 i18n-pot 工具: 这个工具可以扫描你的主题文件，自动生成 .pot 文件，也就是 .po 文件的模板。这能省去你手动查找所有待翻译文本的麻烦。

九、高级技巧：动态文本域和插件兼容

有时候，你可能需要在运行时动态地确定文本域名。例如，你可能想根据用户的选择来加载不同的翻译文件。

<?php
function my_theme_dynamic_textdomain() {
  $locale = get_locale();
  $domain = 'my-theme-' . $locale; // 动态文本域名

  load_textdomain( $domain, get_template_directory() . '/languages/' . $domain . '.mo' );
}
add_action( 'after_setup_theme', 'my_theme_dynamic_textdomain' );
?>

另外，为了确保你的主题与插件兼容，建议使用 apply_filters() 钩子，允许插件修改文本域名和翻译文件路径。

十、常见问题：排查翻译难题

翻译不显示： 检查翻译文件是否已正确加载，文本域名是否一致，翻译函数是否使用正确。
乱码： 确保 .po 和 .mo 文件使用 UTF-8 编码。
缓存： 清除 WordPress 缓存，确保加载最新的翻译文件。

十一、总结：让你的主题走向世界

load_theme_textdomain() 是一个简单但强大的函数，它可以让你的主题支持多语言，走向世界。掌握它的用法，并遵循最佳实践，你就能轻松地创建出国际化的 WordPress 主题。

好了，今天的讲座就到这里，希望大家有所收获！记住，让你的代码说多种语言，世界将更美好！

发表回复 取消回复

发表回复取消回复