云策 WordPress 开发者社区

函数文档

wp_set_script_translations()

查看官方原文 ↗
💡 云策文档标注

概述

wp_set_script_translations() 函数用于为已注册的脚本设置翻译字符串，依赖于 WP_Scripts 类。它通过指定脚本句柄、文本域和翻译文件路径来本地化脚本。

关键要点

  • 函数仅对已注册的脚本生效，需确保脚本已通过 wp_register_script() 或类似方式注册。
  • 参数包括必需的脚本句柄 $handle、可选的文本域 $domain（默认为 'default'）和可选的翻译文件目录路径 $path。
  • 返回布尔值：成功本地化返回 true，否则返回 false。
  • 内部调用 WP_Scripts::set_translations() 方法，需全局 $wp_cripts 实例可用。
  • 从 WordPress 5.1.0 起，$domain 参数变为可选；函数在 5.0.0 版本引入。

代码示例

wp_set_script_translations( 'wpdocs-js', 'wpdocs-text-domain', plugin_dir_path( __FILE__ ) . 'languages' );

注意事项

  • 调用时机：应在脚本加载后调用，例如在 wp_enqueue_scripts 钩子中，优先级可设为较晚（如 100），以避免在脚本注册前执行。
  • 路径处理：使用 plugin_dir_path( __FILE__ ) 获取正确路径，注意它返回带尾部斜杠的路径；避免使用 plugin_basename( __DIR__ ) 等可能导致错误。
  • 自动注册脚本：对于自动注册的脚本（如区块编辑器脚本），句柄可能遵循特定格式（如 [plugin name]-editor-script），可通过 wp_scripts->registered 数组查找。
  • 翻译文件冲突：如果插件在 WordPress 插件目录中有相同语言环境的翻译，使用第三个参数 $path 可能导致翻译不显示，建议使用 WP CLI 生成 JSON 语言包文件。
📄 原文内容

Sets translated strings for a script.

Description

Works only if the script has already been registered.

See also

Parameters

$handlestringrequired
Script handle the textdomain will be attached to.
$domainstringoptional
Text domain. Default 'default'.
$pathstringoptional
The full file path to the directory containing translation files.

Return

bool True if the text domain was successfully localized, false otherwise.

Source

function wp_set_script_translations( $handle, $domain = 'default', $path = '' ) {
	global $wp_scripts;

	if ( ! ( $wp_scripts instanceof WP_Scripts ) ) {
		_wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
		return false;
	}

	return $wp_scripts->set_translations( $handle, $domain, $path );
}

View all references View on Trac View on GitHub

Uses Description
WP_Scripts::set_translations()wp-includes/class-wp-scripts.php

Sets a translation textdomain.
Used by Description
register_block_script_handle()wp-includes/blocks.php

Finds a script handle for the selected block metadata field. It detects when a path to file was provided and optionally finds a corresponding asset file with details necessary to register the script under automatically generated handle name. It returns unprocessed script handle otherwise.

Changelog

Version Description
5.1.0 The $domain parameter was made optional.
5.0.0 Introduced.

User Contributed Notes

  1. Skip to note 5 content


    Ronald Huereca


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    If you have to generate your own JSON language pack files, use WP CLI to generate your JSON file for you. Just navigate to your plugin folder and run the following command.

    wp i18n make-json languages

    Then set the language folder in wp_set_script_translations

    wp_set_script_translations( 'wp-presenter-pro-js', 'wp-presenter-pro', plugin_dir_path( __FILE__ ) . 'languages' );

    Warning: If someone translates your plugin with the same locale on the WordPress Plugin Directory, the language will not show up if using the third argument.

  2. Skip to note 6 content


    Kris Kelvin


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Remember to check the path in the third argument. I wasted 3 days investigating what’s wrong and it turned out I gave 

    plugin_basename( __DIR__ ) . '/languages/'

    instead of 

    plugin_dir_path( __FILE__ ) . '/languages/'

    —

    With plugin_dir_path() works fine.

  3. Skip to note 7 content


    shewa12


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    wp_set_script_translations() should not be called before register or wp_enqueue_scripts or with init hook. To make wordpress able to load handled scripts this function should be called after text domain handled script load. Here is an example:

    add_action( 'wp_enqueue_scripts', array( $this, 'wpdocs_load_scripts' ) );

add_action( 'wp_enqueue_scripts', array( $this, 'wpdocs_load_text_domain' ), 100 );

function wpdocs_load_text_domain() {
    wp_set_script_translations( 
         'wpdocs-js',
         'wpdocs-text-domain',
         plugin_dir_path( __FILE__ ) . 'languages' 
    );
}

  4. Skip to note 8 content


    Lovro Hrust


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    If you do not register script yourself, but rely on automatic script registration, the appropriate handle is in the format [plugin name]-editor-script (as of WP 6.6.1).

    If naming rules change or you want to translate some other automatically registered script, you can find registered scripts in array wp_scripts->registered.

    Naming of the translation files still applies like described in Block editor internationalization.