wp_set_script_translations()
Подключает 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.jswp-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'.
// Важно: вызывайте wp_set_script_translations() после wp_enqueue_script()
Что конкретно сделать этот код:
- Подключит в HTML файл
/wp-includes/js/dist/i18n.min.js. -
Выведет код перевода из найденного json файла.
Файл перевода будет искаться в следующем порядке (он разумеется должен существовать), первый найденный файл будет использован, остальные проигнорированы:
ПУТЬ_ДО_ТЕМЫ/{domain}-{locale}-{handle}.json ПУТЬ_ДО_ТЕМЫ/{domain}-{locale}-{md5}.json /.../wp-content/languages/themes/{domain}-{locale}-{md5}.jsonКак создавать JSON файл перевода смотрите здесь.
-
Подключит в 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 файла переводов через WP-CLI
Если вам нужно сгенерировать собственные файлы JSON языкового пакета, используйте WP CLI. Для этого перейдите в папку вашего плагина и выполните следующую команду.
wp i18n make-json languages
Затем установите папку с языками:
wp_set_script_translations( 'wp-presenter-pro-js', 'wp-presenter-pro', plugin_dir_path( __FILE__ ) . 'languages' );
Предупреждение: Если кто-то переведет ваш плагин с той же локалью в WordPress Plugin Directory, язык не будет отображаться при использовании третьего аргумента.
#3 Как выглядят 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 set script translations WP 6.5.2
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 );
}