WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru

wp_set_script_translations() WP 5.0.0

Подключает JSON файл с переводами строк для указанного JS скрипта (файла).

Также функция добавляет зависимость основного скрипта от библиотеки wp-i18n.

Эта функция — это новый вариант локализации строк в файлах JS. Теперь можно использвоать функции локализации __(), _n(), _x(), _nx(), а также sprintf() прямо в JS. Это стало возможным благодаря пакету wp-i18n, который копирует указанные PHP функции для использования их в JS.

Чтобы понять как это работает, Смотрите пример.

Скрипт, к которому подключается эта функцию обязательно должен быть добавлен в очередь на вывод с помощью wp_enqueue_script().

Если нужен перевод для нескольких JS файлов, то функцию нужно вызвать для каждого файла отдельно.

Обязательно читайте связанную статью: Переводы в JS файлах.

Имя подключаемого json файла

Где, какой и в каком порядке будет искаться .json файл переводов:

  • Когда НЕ указан третий параметр $path (по дефолту):

    /wp-content/languages/themes/{domain}-{locale}-{md5}.json  // plugin-ru_RU-db8f629adc6c4c33f29613cfb71a6038.json
  • Когда указан третий параметр $path:
    УКАЗАННЫЙ_ПУТЬ/{domain}-{locale}-{handle}.json                 // plugin-ru_RU-script.json
    УКАЗАННЫЙ_ПУТЬ/{domain}-{locale}-{md5}.json                    // plugin-ru_RU-db8f629adc6c4c33f29613cfb71a6038.json
    /.../wp-content/languages/themes/{domain}-{locale}-{md5}.json  // plugin-ru_RU-db8f629adc6c4c33f29613cfb71a6038.json

MD5 хэш в имени json файла

При чтении json файлов не всегда возможно заранее знать какой ID (handle) используется при регистрации JS файла, поэтому нужен универсальный механизм поиска json файла перевода. Для этого WP использует в имени файла перевода MD5 хэш из относительного пути js файла. Этот хэш добавляется в конец имени файла перевода: {domain}-{locale}-{md5}.json.

Создается хэш из относительного пути от папки темы/плагина до js файла.

Например, мы подключаем перевод для файла myscript.js, который лежит в теме/плагине в папке:

  • wp-content/mytheme/js/myscript.js
  • wp-content/myplugin/js/myscript.js

В обоих случаях MD5 хэш будет создан из строки md5( 'js/myscript.js' ).

Также, важно заметить, что метка файла .min будет удалена из строки. Например для файла

  • wp-content/myplugin/js/myscript.min.js` Хэш по прежнему будет создан из строкиmd5( 'js/myscript.js' )``.

$relative (относительный) путь перед генерацией хэша можно изменить через фильтр load_script_textdomain_relative_path:

$relative = apply_filters( 'load_script_textdomain_relative_path', $relative, $src );

wp_localize_script() — старый вариант перевода строк для JS файлов.

Хуков нет.

Возвращает

true/false. True когда указанный домен перевода успешно локализован, false в противном случае.

Использование

wp_set_script_translations( $handle, $domain, $path );
$handle(строка) (обязательный)
ID скрипта, к которому нужно применить строки перевода.
$domain(строка)
Домен перевода, который будет использоваться в js в функциях перевода __(), _x(), ...
По умолчанию: 'default'
$path(строка)

Полный путь до директории в которой находится файл перевода.

Если этот параметр не указан, то WP будет искать файл в общем каталоге переводов со следующим названием:

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

Если указать здесь путь, то WP будет искать файл по указанному пути в двух вариациях названий, а также в базовом каталоге переводов:

УКАЗАННЫЙ_ПУТЬ/{domain}-{locale}-{handle}.json
УКАЗАННЫЙ_ПУТЬ/{domain}-{locale}-{md5}.json
/wp-content/languages/themes/{domain}-{locale}-{md5}.json

По умолчанию: null

Примеры

#1 Подключение файла перевода JS и его использование

Подключаем перевод для JS файла scripts.js так:

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

} );

// Важно: Указать одинаковый ID (handle) - 'my-script'.

Что конкретно сделать этот код:

  1. Подключит в HTML файл /wp-includes/js/dist/i18n.min.js.
  2. Выведет код перевода из найденного json файла.

    Файл перевода будет искаться в следующем порядке (он разумеется должен существовать), первый найденный файл будет использован, остальные проигнорированы:

    ПУТЬ_ДО_ТЕМЫ/{domain}-{locale}-{handle}.json
    ПУТЬ_ДО_ТЕМЫ/{domain}-{locale}-{md5}.json
    /.../wp-content/languages/themes/{domain}-{locale}-{md5}.json

    Как создавать JSON файл перевода смотрите здесь.

  3. Подключит в HTML наш JS файл ПУТЬ_ДО_ТЕМЫ/scripts.js.

    В этом файле можно использовать функции перевода строк, например:

    const { __, _x, _n, _nx } = wp.i18n; // создаем алиасы объекта wp.i18n
    
    jQuery(document).ready(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")
    	)
    
    })

#2 Как выглядят JSON данные

Пример того в каком формате хранятся данные в подключаемом json файле.

{
	"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": [ "Привет" ],
			"%s star": [ "%s stars", "%s звезда", "%s звезды", "%s звёзд" ],
			"short word\u0004Hi": [ "Прив" ],
			"superstars\u0004%s star": [ "%s stars", "%s суперзвезда", "%s суперзвезды", "%s суперзвёзд"         ]
		}
	}
}

Заметки

  • Смотрите: WP_Scripts::set_translations()
  • Global. WP_Scripts. $wp_scripts The WP_Scripts object for printing scripts.

Список изменений

С версии 5.0.0 Введена.
С версии 5.1.0 The $domain parameter was made optional.

Код wp set script translations: wp-includes/functions.wp-scripts.php WP 5.4.1

<?php
function wp_set_script_translations( $handle, $domain = 'default', $path = null ) {
	global $wp_scripts;
	if ( ! ( $wp_scripts instanceof WP_Scripts ) ) {
		_wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );
		return false;
	}

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

Cвязанные функции

Из метки: textdomain (файлы переводов po mo)

Еще из раздела: Локализация

Комментариев нет