translate_with_gettext_context()
云策文档标注
概述
translate_with_gettext_context() 是 WordPress 中用于根据上下文获取翻译字符串的核心函数。它通过指定文本、上下文和文本域来检索翻译，若翻译不存在或文本域未加载，则返回原始文本。
关键要点
- 函数作用：基于上下文信息翻译字符串，支持文本域过滤。
- 参数说明：$text（必需，要翻译的文本）、$context（必需，上下文信息）、$domain（可选，文本域，默认 'default'）。
- 返回值：成功时返回翻译后的文本，失败时返回原始文本。
- 注意事项：不建议直接使用此函数，应优先使用 _x() 或相关包装函数。
- 钩子：提供 gettext_with_context 和 gettext_with_context_{$domain} 过滤器，允许自定义翻译逻辑。
- 相关函数：与 get_translations_for_domain()、Translations::translate() 和 apply_filters() 紧密集成。
代码示例
function translate_with_gettext_context( $text, $context, $domain = 'default' ) {
$translations = get_translations_for_domain( $domain );
$translation = $translations->translate( $text, $context );
$translation = apply_filters( 'gettext_with_context', $translation, $text, $context, $domain );
$translation = apply_filters( "gettext_with_context_{$domain}", $translation, $text, $context, $domain );
return $translation;
}注意事项
此函数主要用于内部调用，开发者应使用 _x()、esc_attr_x() 或 esc_html_x() 等高级函数来处理带上下文的翻译，以确保代码可维护性和安全性。
原文内容
Retrieves the translation of $text in the context defined in $context.
Description
If there is no translation, or the text domain isn’t loaded, the original text is returned.
_Note:_ Don’t use translate_with_gettext_context() directly, use _x() or related functions.
Parameters
$textstringrequired-
Text to translate.
$contextstringrequired-
Context information for the translators.
$domainstringoptional-
Text domain. Unique identifier for retrieving translated strings.
Default'default'.
Source
function translate_with_gettext_context( $text, $context, $domain = 'default' ) {
$translations = get_translations_for_domain( $domain );
$translation = $translations->translate( $text, $context );
/**
* Filters text with its translation based on context information.
*
* @since 2.8.0
*
* @param string $translation Translated text.
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$translation = apply_filters( 'gettext_with_context', $translation, $text, $context, $domain );
/**
* Filters text with its translation based on context information for a domain.
*
* The dynamic portion of the hook name, `$domain`, refers to the text domain.
*
* @since 5.5.0
*
* @param string $translation Translated text.
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
$translation = apply_filters( "gettext_with_context_{$domain}", $translation, $text, $context, $domain );
return $translation;
}
Hooks
- apply_filters( ‘gettext_with_context’, string $translation, string $text, string $context, string $domain )
-
Filters text with its translation based on context information.
- apply_filters( “gettext_with_context_{$domain}”, string $translation, string $text, string $context, string $domain )
-
Filters text with its translation based on context information for a domain.