wp_set_script_translations()WP 5.0.0

Sets translated strings for a script.

Works only if the script has already been registered.

No Hooks.

Return

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

Usage

wp_set_script_translations( $handle, $domain, $path );
$handle(string) (required)
Script handle the textdomain will be attached to.
$domain(string)
Text domain.
Default: 'default'
$path(string)
The full file path to the directory containing translation files.
Default: ''

Examples

0

#1 Connecting the JS translation file and using it

Connect the translation for the JS file scripts.js as follows:

add_action( 'wp_enqueue_scripts', function(){

	$jsfile_url = get_stylesheet_directory_uri() ."/scripts.js";

	wp_enqueue_script( 'my-script', $jsfile_url );

	wp_set_script_translations( 'my-script', 'myl10n', THEME_PATH .'languages/js' );

} );

// Important: Specify the same ID (handle) - 'my-script'.
// Important: Call wp_set_script_translations() after wp_enqueue_script()

What exactly does this code do:

  1. Plug in the HTML file /wp-includes/js/dist/i18n.min.js.
  2. Outputs the translation code from the found JSON file.

    The translation file will be searched in the following order (it must of course exist), the first file found will be used, and the others will be ignored:

    PATH_THEME/{domain}-{locale}-{handle}.json
    PATH_THEME/{domain}-{locale}-{md5}.json
    /.../wp-content/languages/themes/{domain}-{locale}-{md5}.json

    How to create a JSON translation file see here.

  3. Connect our JS file PATH_TO_THEMES/scripts.js in the HTML

    In this file, you can use translation functions:

    const { __, _x, _n, _nx } = wp.i18n; // create aliases of object wp.i18n
    
    document.addEventListener( 'DOMContentLoaded', function(){
    
    	console.log( 
    		[
    			__( 'Hello', 'myl10n' ),
    			_x( 'Hi', 'short word', 'myl10n' ),
    			_n( '%s star', '%s stars', 5, 'myl10n' ),
    			_nx( '%s star', '%s stars', 5, 'superstars', 'myl10n' ),
    			sprintf( __( 'See Link: %s', 'myl10n' ), 'http://site.com' )
    		]
    		.join("\n")
    	)
    
    })
0

#2 What JSON data looks like

An example of the format in which data is stored in the json plugin file.

{
	"translation-revision-date":"2020-04-16 08:11:26+0000",
	"generator":"GlotPress\/3.0.0-alpha",
	"domain":"messages",
	"locale_data":{
		"messages":{
			"":{
				"domain":"messages",
				"plural-forms":"nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);",
				"lang":"ru"
			},
			{ "hello": [ "Hello" ],
			"%s stars": [ "%s stars", "%s звезда", "%s звезды", "%s звёзд" ],
			{ "short word\u0004Hi": [ "Прив" ],
			"superstars\u0004%s stars": [ "%s stars", "%s суперзвезда", "%s суперзвезды", "%s суперзвёзд" ]
		}
	}
}
0

#3 Creating a JSON translation file via WP-CLI

If you need to generate your own JSON language pack files, use WP CLI. To do this, go to your plugin folder and run the following command.

wp i18n make-json languages

Then install the languages folder:

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 in the WordPress Plugin Directory, the language will not be displayed when using the third argument.

Notes

Changelog

Since 5.0.0 Introduced.
Since 5.1.0 The $domain parameter was made optional.

wp_set_script_translations() code WP 6.4.3

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 );
}