常用的国际化函数 – WordPress建站指南

要开始对代码进行国际化，您需要了解 WordPress 提供的用于帮助您完成此过程的函数。

在本课中，您将学习 WordPress 中最常用的国际化函数，以及如何在代码中使用它们。

如何对代码进行国际化 (0:18)

每当您编写一段将显示给用户的文本字符串时，都应使用 WordPress 的 i18n 函数，以确保它可以被翻译。

有许多可用的 i18n 函数，每个函数都执行与国际化相关的不同任务。

最常用的 i18n 函数是 __() 函数。此函数接收一个文本字符串，并返回该字符串的翻译版本。如果没有可用的翻译，则返回原始字符串。

您还会注意到，此函数以及大多数其他 i18n 函数都接受第二个参数。此参数用于指定文本域。

文本域是您的插件或主题的唯一标识符。它用于确保使用正确的翻译。

主题和插件在其头部都有一个“文本域”字段。这用于指定主题或插件的文本域。

每当您使用翻译函数时，都应始终将文本域作为第二个参数包含在内。

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

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

首先，浏览到 GitHub 上的“初学者开发者学习路径”仓库，并下载“国际化主题”zip 文件。

然后，在您的 WordPress 网站上安装该主题，并在代码编辑器中浏览它。

在 functions.php 文件中，一个 JavaScript 文件在 WordPress 仪表盘的上下文中被入队。它还在“外观”菜单中注册了一个子菜单项，用于渲染主题设置页面。

<?php
/**
 * Enqueue theme.js file in the dashboard.
 */
add_action( 'admin_enqueue_scripts', 'internationalization_enqueue_scripts' );
function internationalization_enqueue_scripts() {
    wp_enqueue_script(
        'internationalization-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', 'internationalization_add_submenu_page' );
function internationalization_add_submenu_page() {
    add_submenu_page(
        'themes.php',
        'Internationalization',
        'Internationalization',
        'manage_options',
        'internationalization',
        'internationalization_display_page'
    );
}

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

如果您浏览到设置页面，它会包含一个按钮，点击该按钮会显示一个警告框。

此警告框由主题的 JavaScript 文件处理。

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

在这段代码中，您有许多需要国际化的英文字符串。

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

首先检查主题的文本域。对于主题，这位于 style.css 文件中；对于插件，则位于主插件文件中。

在这种情况下，文本域是 internationalization。如果此主题没有文本域，您需要指定一个。

然后，更新 internationalization_add_submenu_page() 函数中的文本字符串。

/**
 * Create an admin submenu item under the "Appearance" menu.
 */
add_action( 'admin_menu', 'internationalization_add_submenu_page' );
function internationalization_add_submenu_page() {
    add_submenu_page(
        'themes.php',
        __( 'Internationalization', 'internationalization' ),
        __( 'Internationalization', 'internationalization' ),
        'manage_options',
        'internationalization',
        'internationalization_display_page'
    );
}

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

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

WordPress 还包含一个用于直接输出可翻译字符串的简写函数。此函数是 _e() 函数。它既进行国际化，又直接输出字符串。您可以使用此函数来简化代码。

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

接下来，您需要国际化 JavaScript 文件中的文本字符串。

为此，有一个与 PHP 的 __() 函数等效的 JavaScript 版本，它在 WordPress 前端的 wp.i18n 对象中可用。

为了确保您可以使用此函数，您需要更新您的 internationalization_enqueue_scripts() 函数，以将 wp-i18n 包作为依赖项。这将确保您的 JavaScript 代码仅在 wp-i18n 包加载且 wp.i18n 对象可用时才会被加载。

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

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

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

完成此操作后，您就可以设置并使用来自 wp.i18n 对象的 __() 函数来翻译 JavaScript 文件中的文本字符串。

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

如果您刷新页面，不会立即看到任何变化，所有功能仍将按预期工作。

但是，如果有人愿意，他们可以基于所有国际化的文本字符串为主题生成英文语言文件，以便进行翻译。

块开发中的国际化函数

如果您正在为块编辑器开发一个块，您也可以在块的 JavaScript 中使用 JavaScript 翻译函数来国际化块中的文本字符串。

您需要做的就是从 @wordpress/i18n 包中导入相关函数。

/**
 * Retrieves the translation of text.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/
 */
import { __ } from '@wordpress/i18n';

进一步阅读

本课程仅涵盖部分可用的国际化函数。如需了解所有可用函数的更多信息，请查阅 WordPress 开发者资源中通用 API 手册的国际化章节。

如何对代码进行国际化 (0:18)

块开发中的国际化函数

进一步阅读

发表回复 取消回复

发表回复取消回复