发布于 由admin

详解 WordPress `get_locale()` 函数的源码：如何获取当前站点的本地化语言。

各位观众老爷们，晚上好！ 欢迎来到今天的“扒一扒 WordPress 源码”特别节目。今天我们要聊的，是 WordPress 中一个不起眼，但又极其重要的函数：get_locale()。它就像一个默默工作的翻译官，告诉 WordPress 你的站点应该用什么语言显示。

准备好跟我一起深入 get_locale() 的世界了吗？系好安全带，发车咯！

get_locale()：你的站点语言管家

首先，让我们来明确一下 get_locale() 的作用。简单来说，它负责返回当前 WordPress 站点使用的本地化语言代码。这个语言代码遵循 ISO 639 标准，比如 zh_CN 代表简体中文，en_US 代表美式英语。

这个函数在 WordPress 的本地化（Localization，简称 L10n）和国际化（Internationalization，简称 i18n）中扮演着核心角色。WordPress 通过语言包（.mo 文件）来实现不同语言的显示，而 get_locale() 就像一个钥匙，告诉 WordPress 应该使用哪个语言包。

源码剖析：get_locale() 的内心世界

好了，废话不多说，直接上代码，看看 get_locale() 到底是怎么工作的。在 WordPress 源码中，get_locale() 的定义通常位于 wp-includes/l10n.php 文件中（具体位置可能会因 WordPress 版本而略有差异）。

/**
 * Retrieves the current locale.
 *
 * @since 1.5.0
 *
 * @global WP_Locale $wp_locale WordPress locale object.
 *
 * @return string The locale of the blog or 'en_US' if one is not set.
 */
function get_locale() {
    global $wp_locale;

    // 1. 从全局变量中获取
    if ( isset( $wp_locale ) && ! empty( $wp_locale->locale ) ) {
        return $wp_locale->locale;
    }

    // 2. 从 options 表中获取 'WPLANG' 选项
    $locale = get_option( 'WPLANG' );

    // 3. 如果 'WPLANG' 为空，则返回 'en_US'
    if ( empty( $locale ) ) {
        $locale = 'en_US';
    }

    // 4. 应用 'locale' filter
    return apply_filters( 'locale', $locale );
}

这段代码看起来是不是很简单？但麻雀虽小，五脏俱全。让我们逐行分析：

  1. global $wp_locale;: 这里声明了一个全局变量 $wp_locale。这个变量是一个 WP_Locale 类的实例，它包含了当前站点的本地化信息，包括语言代码、文本方向等等。WP_Locale 类定义在 wp-includes/l10n.php 中，有兴趣的同学可以自行查阅。

  2. if ( isset( $wp_locale ) && ! empty( $wp_locale->locale ) ) { return $wp_locale->locale; }: 首先检查 $wp_locale 是否已经设置，并且它的 locale 属性（存储语言代码）是否为空。如果都满足，就直接返回 $wp_locale->locale 的值。 这一步实际上是尝试从已经加载的本地化信息中获取语言代码，避免重复读取配置。

  3. $locale = get_option( 'WPLANG' );: 如果 $wp_locale 没有设置，或者 $wp_locale->locale 为空，就尝试从 WordPress 的 options 表中获取 WPLANG 选项的值。 WPLANG 选项存储了用户在 WordPress 后台设置的语言代码。 get_option() 函数是 WordPress 提供的一个用于获取选项值的函数。

  4. if ( empty( $locale ) ) { $locale = 'en_US'; }: 如果 WPLANG 选项为空，说明用户没有明确设置语言，那么就默认使用 en_US （美式英语）作为语言代码。

  5. return apply_filters( 'locale', $locale );: 最后，也是最重要的一步，使用 apply_filters( 'locale', $locale ) 对语言代码进行过滤。 apply_filters() 函数是 WordPress 的一个强大的钩子机制，允许插件或主题修改 WordPress 的核心行为。 在这里，locale 是一个 filter hook，插件或主题可以通过这个 hook 来修改 get_locale() 返回的语言代码。

流程图解：get_locale() 的寻 language 之路

为了更好地理解 get_locale() 的工作流程，我们可以用一个简单的流程图来表示：

graph TD
    A[开始] --> B{是否存在 $wp_locale 且 $wp_locale->locale 不为空?};
    B -- 是 --> C[返回 $wp_locale->locale];
    B -- 否 --> D[从 options 表中获取 'WPLANG' 选项];
    D --> E{WPLANG 是否为空?};
    E -- 是 --> F[设置 $locale = 'en_US'];
    E -- 否 --> G[设置 $locale = WPLANG 的值];
    F --> H[使用 apply_filters( 'locale', $locale ) 进行过滤];
    G --> H;
    H --> I[返回 $locale];
    C --> I;
    I --> J[结束];

apply_filters( 'locale', $locale )：修改语言代码的秘密通道

刚才我们提到了 apply_filters( 'locale', $locale ) 这个函数。 它允许插件或主题通过 locale filter hook 来修改 get_locale() 返回的语言代码。 这为我们提供了极大的灵活性，可以根据不同的情况动态地设置语言。

例如，我们可以根据用户的 IP 地址来判断用户所在的国家，然后设置相应的语言代码。 或者，我们可以根据用户的浏览器语言设置来设置语言代码。

下面是一个简单的示例，演示如何使用 locale filter hook 来修改语言代码：

/**
 * 根据用户 IP 地址设置语言代码
 */
function my_custom_locale( $locale ) {
    // 假设我们有一个函数可以根据 IP 地址获取国家代码
    $country_code = get_country_code_by_ip( $_SERVER['REMOTE_ADDR'] );

    if ( $country_code == 'CN' ) {
        return 'zh_CN'; // 简体中文
    } elseif ( $country_code == 'TW' ) {
        return 'zh_TW'; // 繁体中文
    } else {
        return $locale; // 使用默认语言
    }
}

add_filter( 'locale', 'my_custom_locale' );

这段代码首先定义了一个名为 my_custom_locale 的函数，这个函数接收一个参数 $locale，它就是 get_locale() 函数原本要返回的语言代码。 然后，我们使用 add_filter( 'locale', 'my_custom_locale' ) 将这个函数添加到 locale filter hook 上。

当 WordPress 调用 get_locale() 函数时，它会执行 apply_filters( 'locale', $locale )， 这会依次执行所有添加到 locale filter hook 上的函数，包括我们的 my_custom_locale 函数。 my_custom_locale 函数会根据用户的 IP 地址来判断用户所在的国家，然后设置相应的语言代码。

get_locale() 的应用场景：让你的站点说多国语言

get_locale() 函数在 WordPress 中有着广泛的应用，主要体现在以下几个方面：

  • 加载语言包： WordPress 根据 get_locale() 返回的语言代码来加载相应的语言包（.mo 文件），从而实现不同语言的显示。
  • 格式化日期和时间： 不同的语言有不同的日期和时间格式。get_locale() 可以帮助 WordPress 使用正确的格式来显示日期和时间。
  • 翻译文本： WordPress 使用 __()、_e() 等函数来翻译文本。这些函数会根据 get_locale() 返回的语言代码来查找对应的翻译。
  • 插件和主题的本地化： 插件和主题也可以使用 get_locale() 函数来实现本地化，让它们能够显示不同的语言。

实例演示：让你的插件支持多语言

假设我们正在开发一个简单的 WordPress 插件，用于显示当前的日期和时间。 为了让这个插件支持多语言，我们可以使用 get_locale() 函数来实现本地化。

首先，我们需要创建一个插件文件，例如 my-date-plugin.php。 在这个文件中，我们可以定义一个函数来显示当前的日期和时间：

<?php
/**
 * Plugin Name: My Date Plugin
 * Description: A simple plugin to display the current date and time.
 * Version: 1.0.0
 */

function my_date_plugin_display_date_time() {
    $date_format = __('l, F j, Y', 'my-date-plugin'); // 日期格式
    $time_format = __('g:i a', 'my-date-plugin'); // 时间格式

    $date = date_i18n( $date_format );
    $time = date_i18n( $time_format );

    echo '<p>' . sprintf( __('Today is %1$s and the time is %2$s', 'my-date-plugin'), $date, $time ) . '</p>';
}

add_shortcode( 'my_date', 'my_date_plugin_display_date_time' );

在这个代码中，我们使用了 __() 函数来翻译文本。 __() 函数接收两个参数：要翻译的文本和一个文本域（text domain）。 文本域用于标识插件或主题，可以避免不同插件或主题之间的翻译冲突。

我们还使用了 date_i18n() 函数来格式化日期和时间。 date_i18n() 函数会根据 get_locale() 返回的语言代码来使用正确的日期和时间格式。

为了让插件能够显示不同的语言，我们需要创建语言包（.po 和 .mo 文件）。 可以使用 Poedit 等工具来创建和编辑语言包。

创建好语言包后，需要将它们放到插件的 languages 目录下。 WordPress 会自动加载这些语言包，从而实现插件的本地化。

总结：get_locale()，小函数，大作用

get_locale() 函数虽然代码简单，但它在 WordPress 的本地化和国际化中扮演着至关重要的角色。 它就像一个翻译官，告诉 WordPress 应该使用什么语言来显示站点内容。

通过深入了解 get_locale() 的源码，我们可以更好地理解 WordPress 的本地化机制，从而开发出更加国际化的插件和主题。

一些补充说明：

知识点 说明
WP_Locale 类 包含了当前站点的本地化信息，包括语言代码、文本方向等。
WPLANG 选项 存储了用户在 WordPress 后台设置的语言代码。
apply_filters() WordPress 的钩子机制，允许插件或主题修改 WordPress 的核心行为。
__() 函数 用于翻译文本。
date_i18n() 函数 用于格式化日期和时间，会根据 get_locale() 返回的语言代码来使用正确的格式。
语言包 (.po 和 .mo 文件) 包含了不同语言的翻译文本。

好了，今天的“扒一扒 WordPress 源码”特别节目就到这里。 希望大家通过今天的学习，对 get_locale() 函数有了更深入的了解。 下次再见！ 拜拜！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注