load_script_translations()
云策文档标注
概述
load_script_translations() 函数用于加载指定脚本句柄和文本域的翻译数据。它通过读取翻译文件并返回 JSON 编码的翻译字符串，支持通过过滤器进行自定义。
关键要点
- 函数接受三个参数：$file（翻译文件路径，若无则为 false）、$handle（脚本句柄）和 $domain（文本域）。
- 返回 JSON 编码的翻译字符串，若无翻译数据则返回 false。
- 包含三个过滤器：pre_load_script_translations（预过滤翻译数据）、load_script_translation_file（过滤文件路径）和 load_script_translations（过滤翻译数据）。
- 函数首先检查 pre_load_script_translations 过滤器，若返回非 null 值则直接返回，否则继续处理。
- 通过 load_script_translation_file 过滤器调整文件路径，然后检查文件可读性，最后读取文件内容并应用 load_script_translations 过滤器。
代码示例
function load_script_translations( $file, $handle, $domain ) {
$translations = apply_filters( 'pre_load_script_translations', null, $file, $handle, $domain );
if ( null !== $translations ) {
return $translations;
}
$file = apply_filters( 'load_script_translation_file', $file, $handle, $domain );
if ( ! $file || ! is_readable( $file ) ) {
return false;
}
$translations = file_get_contents( $file );
return apply_filters( 'load_script_translations', $translations, $file, $handle, $domain );
}注意事项
- 确保翻译文件路径正确且可读，否则函数返回 false。
- 利用过滤器可以灵活覆盖默认逻辑，例如通过 pre_load_script_translations 直接提供翻译数据。
- 函数自 WordPress 5.0.2 版本引入，主要用于支持脚本本地化。
原文内容
Loads the translation data for the given script handle and text domain.
Parameters
$filestring|falserequired-
Path to the translation file to load. False if there isn’t one.
$handlestringrequired-
Name of the script to register a translation domain to.
$domainstringrequired-
The text domain.
Source
function load_script_translations( $file, $handle, $domain ) {
/**
* Pre-filters script translations for the given file, script handle and text domain.
*
* Returning a non-null value allows to override the default logic, effectively short-circuiting the function.
*
* @since 5.0.2
*
* @param string|false|null $translations JSON-encoded translation data. Default null.
* @param string|false $file Path to the translation file to load. False if there isn't one.
* @param string $handle Name of the script to register a translation domain to.
* @param string $domain The text domain.
*/
$translations = apply_filters( 'pre_load_script_translations', null, $file, $handle, $domain );
if ( null !== $translations ) {
return $translations;
}
/**
* Filters the file path for loading script translations for the given script handle and text domain.
*
* @since 5.0.2
*
* @param string|false $file Path to the translation file to load. False if there isn't one.
* @param string $handle Name of the script to register a translation domain to.
* @param string $domain The text domain.
*/
$file = apply_filters( 'load_script_translation_file', $file, $handle, $domain );
if ( ! $file || ! is_readable( $file ) ) {
return false;
}
$translations = file_get_contents( $file );
/**
* Filters script translations for the given file, script handle and text domain.
*
* @since 5.0.2
*
* @param string $translations JSON-encoded translation data.
* @param string $file Path to the translation file that was loaded.
* @param string $handle Name of the script to register a translation domain to.
* @param string $domain The text domain.
*/
return apply_filters( 'load_script_translations', $translations, $file, $handle, $domain );
}
Hooks
- apply_filters( ‘load_script_translations’, string $translations, string $file, string $handle, string $domain )
-
Filters script translations for the given file, script handle and text domain.
- apply_filters( ‘load_script_translation_file’, string|false $file, string $handle, string $domain )
-
Filters the file path for loading script translations for the given script handle and text domain.
- apply_filters( ‘pre_load_script_translations’, string|false|null $translations, string|false $file, string $handle, string $domain )
-
Pre-filters script translations for the given file, script handle and text domain.
Changelog
| Version | Description |
|---|---|
| 5.0.2 | Introduced. |