_load_textdomain_just_in_time()
云策文档标注
概述
_load_textdomain_just_in_time() 是 WordPress 核心函数，用于按需加载插件和主题的文本域翻译文件。它自动从 wp-content/languages 目录查找翻译，无需手动调用 load_plugin_textdomain() 或 load_theme_textdomain()。
关键要点
- 函数在首次遇到文本域时触发，尝试加载对应的 .mo 翻译文件
- 参数 $domain 为必需字符串，表示文本域的唯一标识符
- 返回布尔值：成功加载返回 true，失败返回 false
- 内部使用 WP_Textdomain_Registry 来管理翻译文件路径
- 如果翻译加载过早（在 'after_setup_theme' 动作之前），会触发 _doing_it_wrong() 警告
- 支持主题语言目录在 WP_LANG_DIR 之外的特殊情况处理
代码示例
function _load_textdomain_just_in_time( $domain ) {
/** @var WP_Textdomain_Registry $wp_textdomain_registry */
global $l10n_unloaded, $wp_textdomain_registry;
$l10n_unloaded = (array) $l10n_unloaded;
// Short-circuit if domain is 'default' which is reserved for core.
if ( 'default' === $domain || isset( $l10n_unloaded[ $domain ] ) ) {
return false;
}
if ( ! $wp_textdomain_registry->has( $domain ) ) {
return false;
}
$locale = determine_locale();
$path = $wp_textdomain_registry->get( $domain, $locale );
if ( ! $path ) {
return false;
}
if ( ! doing_action( 'after_setup_theme' ) && ! did_action( 'after_setup_theme' ) ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: 1: The text domain. 2: 'init'. */
__( 'Translation loading for the %1$s domain was triggered too early. This is usually an indicator for some code in the plugin or theme running too early. Translations should be loaded at the %2$s action or later.' ),
'' . $domain . '',
'init'
),
'6.7.0'
);
}
// Themes with their language directory outside of WP_LANG_DIR have a different file name.
$template_directory = trailingslashit( get_template_directory() );
$stylesheet_directory = trailingslashit( get_stylesheet_directory() );
if ( str_starts_with( $path, $template_directory ) || str_starts_with( $path, $stylesheet_directory ) ) {
$mofile = "{$path}{$locale}.mo";
} else {
$mofile = "{$path}{$domain}-{$locale}.mo";
}
return load_textdomain( $domain, $mofile, $locale );
}注意事项
- 此函数自 WordPress 4.6.0 版本引入
- 避免在 'after_setup_theme' 动作之前调用，否则会触发警告
- 文本域 'default' 保留给核心使用，不会加载
- 依赖 WP_Textdomain_Registry 来注册和获取翻译路径
原文内容
Loads plugin and theme text domains just-in-time.
Description
When a textdomain is encountered for the first time, we try to load the translation file from wp-content/languages, removing the need to call load_plugin_textdomain() or load_theme_textdomain() .
Parameters
$domainstringrequired-
Text domain. Unique identifier for retrieving translated strings.
Source
function _load_textdomain_just_in_time( $domain ) {
/** @var WP_Textdomain_Registry $wp_textdomain_registry */
global $l10n_unloaded, $wp_textdomain_registry;
$l10n_unloaded = (array) $l10n_unloaded;
// Short-circuit if domain is 'default' which is reserved for core.
if ( 'default' === $domain || isset( $l10n_unloaded[ $domain ] ) ) {
return false;
}
if ( ! $wp_textdomain_registry->has( $domain ) ) {
return false;
}
$locale = determine_locale();
$path = $wp_textdomain_registry->get( $domain, $locale );
if ( ! $path ) {
return false;
}
if ( ! doing_action( 'after_setup_theme' ) && ! did_action( 'after_setup_theme' ) ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: 1: The text domain. 2: 'init'. */
__( 'Translation loading for the %1$s domain was triggered too early. This is usually an indicator for some code in the plugin or theme running too early. Translations should be loaded at the %2$s action or later.' ),
'<code>' . $domain . '</code>',
'<code>init</code>'
),
'6.7.0'
);
}
// Themes with their language directory outside of WP_LANG_DIR have a different file name.
$template_directory = trailingslashit( get_template_directory() );
$stylesheet_directory = trailingslashit( get_stylesheet_directory() );
if ( str_starts_with( $path, $template_directory ) || str_starts_with( $path, $stylesheet_directory ) ) {
$mofile = "{$path}{$locale}.mo";
} else {
$mofile = "{$path}{$domain}-{$locale}.mo";
}
return load_textdomain( $domain, $mofile, $locale );
}
Changelog
| Version | Description |
|---|---|
| 4.6.0 | Introduced. |