学习WordPress——通用 API 国际化

国际化是什么，以及它为何如此关键。教你如何在 WordPress 代码里应用国际化，让你的网站跨越语言的障碍，触及全球用户。

什么是国际化？

国际化是以可以轻松翻译成其他语言的方式开发应用程序的过程。国际化通常缩写为 i18n（因为字母 i 和 n 之间有 18 个字母）。

WordPress 在世界各地被使用多种语言的人们使用。

因此，WordPress 中的任何文本字符串都需要进行编码，以便可以轻松地将它们翻译成其他语言。

确保文本字符串可以翻译的过程称为国际化，而翻译字符串并将其适应特定位置的过程称为本地化。

虽然本地化超出了本教程的范围，但您可以在通用 API 手册的本地化部分阅读更多相关信息。

作为开发人员，您可能无法为所有用户提供本地化服务；但是，使用 i18n 函数和工具创建特定文件，翻译人员可以成功本地化您的代码，而无需修改源代码本身。

国际化不是什么

国际化不同于确保您的内容在网站前端以多种语言提供。这通常被称为确保您的内容是多语言的或经过翻译的。由于内容存储在数据库中，因此最好为您想要支持的每种语言准备一份完全翻译的网站副本。这可以使用TranslatePress、Polylang或WeGlot 等插件来实现。

如何国际化你的代码

每当您发现自己正在编写要向用户显示的文本字符串时，您应该使用WordPress i18n 函数来确保它可以被翻译。有许多可用的 i18n 函数，每个函数执行与国际化相关的不同任务。

让我们看一下最基本的 i18n 函数：__() function。该函数接受一个文本字符串并返回该字符串的翻译版本。如果没有可用的翻译，则返回原始字符串。

您还会注意到该函数和大多数其他 i18n 函数都采用第二个参数。该参数用于指定文本域。文本域是您的插件或主题的唯一标识符。它用于确保加载正确的翻译文件。

文本域还用于创建翻译文件。最终的翻译文件存储在languages您的插件或主题的文件夹中。文件名是带有.mo扩展名的文本域。例如，如果您的文本域是my-textdomain，则翻译文件将为my-textdomain.mo。

__( 'Some Text', 'my-textdomain' );

要了解其工作原理，让我们看一下示例：

在该functions.php文件中，JavaScript 文件在 WordPress 仪表板的上下文中排队，它还在外观菜单中注册了一个子菜单项，该子菜单项呈现子主题设置页面。

<?php
/**
 * Enqueue theme.js file in the dashboard.
 */
add_action( 'admin_enqueue_scripts', 'twentytwentythreechild_enqueue_scripts' );
function twentytwentythreechild_enqueue_scripts() {
    wp_enqueue_script(
        'twentytwentythreechild-theme-js',
        get_stylesheet_directory_uri() . '/assets/theme.js',
        array(),
        '1.0.0',
        true
    );
}

/**
 * Create a submenu item under the "Appearance" menu.
 */
add_action( 'admin_menu', 'twentytwentythreechild_add_submenu_page' );
function twentytwentythreechild_add_submenu_page() {
    add_submenu_page(
        'themes.php', 
        'Twenty Twenty Three Child', 
        'Twenty Twenty Three Child',
        'manage_options', 
        'twentytwentythreechild', 
        'twentytwentythreechild_display_page' 
    );
}

/**
 * Render the page for the submenu item.
 */
function twentytwentythreechild_display_page() {
    ?>
    <div class="wrap">
        <h1>Twenty Twenty Three Child Settings</h1>
        <p>This is a settings page for the Twenty Twenty Three Child theme</p>
        <button id="twentytwentythreechild-settings-button" class="button button-primary">Alert</button>
    </div>
    <?php
}

设置页面包含一个按钮，单击该按钮会显示警报。

此警报在主题的 JavaScript 文件中处理。

/**
 * Add event listener to the button
 */
document.querySelector( '#twentytwentythreechild-settings-button' ).addEventListener( 'click', function(){
    alert( 'Settings button clicked' );
} );

在此代码中，您有许多需要翻译的英文文本字符串。

第一步是国际化 PHP 代码中的文本字符串。为此，您可以在__()函数中包装文本字符串并指定文本域。

首先更新函数中的文本字符串twentytwentythreechild_add_submenu_page()。

/**
 * Create an admin submenu item under the "Appearance" menu.
 */
add_action( 'admin_menu', 'twentytwentythreechild_add_submenu_page' );
function twentytwentythreechild_add_submenu_page() {
    add_submenu_page(
        'themes.php', // parent slug
        __( 'Twenty Twenty Three Child', 'twentytwentythreechild' ), // page title
        __( 'Twenty Twenty Three Child', 'twentytwentythreechild' ), // menu title
        'manage_options', // capability
        'twentytwentythreechild', // slug
        'twentytwentythreechild_display_page' // callback
    );
}

您可以对函数中的文本字符串执行相同的操作twentytwentythreechild_display_page()。

/**
 * Render the page for the submenu item.
 */
function twentytwentythreechild_display_page() {
    ?>
    <div class="wrap">
        <h1><?php echo __( 'Twenty Twenty Three Child Settings', 'twentytwentythreechild' ); ?></h1>
        <p><?php echo __( 'This is a settings page for the Twenty Twenty Three Child theme', '__' ); ?></p>
        <button id="twentytwentythreechild-settings-button" class="button button-primary"><?php echo __( 'Alert', 'twentytwentythreechild' ); ?></button>
    </div>
    <?php
}

WordPress 还包含一个速记函数来回显可翻译的字符串。这个函数就是_e()函数。它既翻译又回显字符串。您可以使用此函数来简化您的代码。

function twentytwentythreechild_display_page() {
    ?>
    <div class="wrap">
        <h1><?php _e( 'Twenty Twenty Three Child Settings', 'twentytwentythreechild' ); ?></h1>
        <p><?php _e( 'This is a settings page for the Twenty Twenty Three Child theme', '__' ); ?></p>
        <button id="twentytwentythreechild-settings-button" class="button button-primary"><?php _e( 'Alert', 'twentytwentythreechild' ); ?></button>
    </div>
    <?php
}

接下来，您需要对 JavaScript 文件中的文本字符串进行国际化。为此，有一个与 PHP__()函数等效的 JavaScript，可在 WordPress 前端的 wp.i18n 对象中使用。为了确保您可以使用此函数，您需要更新您的twentytwentythreechild_enqueue_scripts()函数以要求该wp-i18n包作为依赖项。这将确保仅在wp-i18n加载包且wp.i18n对象可用时才加载 JavaScript 代码。

/**
 * Enqueue theme.js file in the dashboard.
 */
add_action( 'admin_enqueue_scripts', 'twentytwentythreechild_enqueue_scripts' );
function twentytwentythreechild_enqueue_scripts() {
    wp_enqueue_script(
        'twentytwentythreechild-theme-js',
        get_stylesheet_directory_uri() . '/assets/theme.js',
        array( 'wp-i18n' ),
        '1.0.0',
        true
    );
}

然后，您需要调用要翻译的脚本的wp_set_script_translations函数。该函数将脚本句柄和文本域作为参数。这将加载脚本的翻译。

wp_set_script_translations( 'twentytwentythreechild-theme-js', 'twentytwentythreechild' );

完成此操作后，您就可以使用该__()函数来翻译 JavaScript 文件中的文本字符串。

/**
 * Add event listener to the button
 */
document.querySelector( '#twentytwentythreechild-settings-button' ).addEventListener( 'click', function(){
    alert( __( 'Settings button clicked', 'twentytwentythreechild' ) );
} );

如何测试您的国际化功能

一旦您将代码设置为使用 i18n 函数，您就可以通过生成 POT 文件来测试它。这是翻译人员用来创建翻译文件的文件。您可以使用WP CLI生成 POT 文件。

wp i18n make-pot path/to/your/plugin/or/theme

这将扫描插件或主题中的代码，找到任何可翻译的字符串，并将它们放入 POT 文件中。

国际化指南

国际化代码时遵循最佳实践非常重要。

在 WordPress 开发者资源的通用 API 部分的国际化下，有一个关于国际化指南的页面，熟悉一下就好了。

此外，如果您计划将主题提交到 WordPress 主题目录，您应该阅读主题审查手册中有关语言和国际化的部分。

这将扫描插件或主题中的代码，找到任何可翻译的字符串，并将它们放入 POT 文件中。

国际化指南

国际化代码时遵循最佳实践非常重要。

在 WordPress 开发者资源的通用 API 部分的国际化下，有一个关于国际化指南的页面，熟悉一下就好了。

此外，如果您计划将主题提交到 WordPress 主题目录，您应该阅读主题审查手册中有关语言和国际化的部分。