国际化过滤器

查看官方原文 ↗

💡 云策文档标注

概述

本文档介绍了 WordPress 中用于过滤 i18n 函数（如 __(), _x(), _n(), _nx()）返回值的过滤器，允许开发者覆盖字符串翻译。这些过滤器包括 i18n.gettext、i18n.gettext_with_context、i18n.ngettext 和 i18n.ngettext_with_context，并支持基于文本域（text domain）的特定过滤器以提高性能。

关键要点

i18n 过滤器可用于动态修改翻译字符串，适用于自定义插件或主题开发。
过滤器参数与对应的 PHP 函数参数一致，例如 translation、text、domain 等。
推荐使用文本域特定的过滤器（如 i18n.gettext_woocommerce）以减少回调执行次数，提升性能。
对于未定义文本域的字符串（如 WordPress 核心字符串），使用“default”作为文本域（如 i18n.gettext_default）。

代码示例

// 使用 i18n.gettext 过滤器覆盖特定翻译
function myPluginGettextFilter( translation, text, domain ) {
    if ( text === 'Create Reusable block' ) {
        return 'Save to MyOrg block library';
    }
    return translation;
}

// 添加过滤器
wp.hooks.addFilter(
    'i18n.gettext',
    'my-plugin/override-add-to-reusable-blocks-label',
    myPluginGettextFilter
);

注意事项

在应用过滤器时，确保回调函数正确处理参数并返回适当的翻译值。
使用文本域特定过滤器时，需将文本域附加到标准过滤器名称后（如 i18n.gettext_woocommerce）。

📄 原文内容

The i18n functions (__(), _x(), _n() and _nx()) provide translations of strings for use in your code. The values returned by these functions are filterable if you need to override them, using the following filters:

i18n.gettext
i18n.gettext_with_context
i18n.ngettext
i18n.ngettext_with_context

Filter Arguments

The filters are passed the following arguments, in line with their PHP equivalents.

i18n.gettext

function i18nGettextCallback( translation, text, domain ) {
    return translation;
}

i18n.gettext_with_context

function i18nGettextWithContextCallback( translation, text, context, domain ) {
    return translation;
}

i18n.ngettext

function i18nNgettextCallback( translation, single, plural, number, domain ) {
    return translation;
}

i18n.ngettext_with_context

function i18nNgettextWithContextCallback(
    translation,
    single,
    plural,
    number,
    context,
    domain
) {
    return translation;
}

Basic Example

Here is a simple example, using the i18n.gettext filter to override a specific translation.

// Define our filter callback.
function myPluginGettextFilter( translation, text, domain ) {
    if ( text === 'Create Reusable block' ) {
        return 'Save to MyOrg block library';
    }
    return translation;
}

// Adding the filter
wp.hooks.addFilter(
    'i18n.gettext',
    'my-plugin/override-add-to-reusable-blocks-label',
    myPluginGettextFilter
);

Using ‘text domain’-specific filters

Filters that are specific to the text domain you’re operating on are generally preferred for performance reasons (since your callback will only be run for strings in the relevant text domain).

To attach to a text domain-specific filter append an underscore and the text-domain to the standard filter name. For example, if filtering a string where the text domain is “woocommerce”, you would use one of the following filters:

i18n.gettext_woocommerce
i18n.gettext_with_context_woocommerce
i18n.ngettext_woocommerce
i18n.ngettext_with_context_woocommerce

For example:

// Define our filter callback.
function myPluginGettextFilter( translation, text, domain ) {
    if ( text === 'You’ve fulfilled all your orders' ) {
        return 'All packed up and ready to go. Good job!';
    }
    return translation;
}

// Adding the filter
wp.hooks.addFilter(
    'i18n.gettext_woocommerce',
    'my-plugin/override-fulfilled-all-orders-text',
    myPluginGettextFilter
);

Note: To apply a filter where the text-domain is undefined (for example WordPress core strings), then use the name “default” to construct the filter name.

i18n.gettext_default
i18n.gettext_with_context_default
i18n.ngettext_default
i18n.ngettext_with_context_default

云策 WordPress 开发者社区

块编辑器开发文档