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.5

<?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__, $handle );
		return false;
	}

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

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

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

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

2 коммента
  • Радикальная у них там ошибка, WP-CLI собирает md5 четко из имени файла, а при подключении json перевода WP ищет файл с именем, представляющим из себя md5 относительного пути к файлу от папки темы (в случае с темой). И все разваливается....

    wp-includes\l10n.php:1021
    $md5_filename = $file_base . '-' . md5( $relative ) . '.json';

    Вот здесь $relative это что-то типа includes/assets/js/blocks/block-objects-reviews.js, хотя в WP-CLI назовет при создании перевода файл так md5('block-objects-reviews.js');

    WP конечно файл не обнаружит и передаст все это в load_script_translations(), а в нем имя файла в md5 вообще не проверяется, а четко ищется файл по маршруту, который соответствует зарегистрированному скрипту.

    Поэтому подключить json перевод имея оригинальный файл сформированный WP-CLI вообще невозможно. Его надо переименовать ручками в handle зарегистрированного скрипта. Либо в помощь:

    apply_filters( 'load_script_translation_file', $file, $handle, $domain );

    Вообще все это чудовищно... Создай POT, потом создай po, потом переделай его в JSON, потом его переименуй...

    И так - для каждого скрипта.. Идиотизм.

    1
    Ответитьмесяц назад #
    • Kama7773

      Поэтому подключить json перевод имея оригинальный файл сформированный WP-CLI вообще невозможно.

      Возможно конечно, я ведь подключал! Там не должно ничего разваливаться. Тебе нужно правильно создать PO файл - чтобы в его настройках при парсинге базовый путь поиска был "от темы", тогда в нем, для строк, пути файлов будут указаны также "от темы" и из них создастся хэш и также "от темы" будет создан хэш самим ВП при поиске файла и все совпадет - файл будет найден. Вот это внимательно прочитай.

      В строках перевода путь должен быть правильный, например для темы так, когда мы создаем перевод для файла scripts.js, который лежит в папке темы js:

      #: js/scripts.js:9
      msgid "Hello"
      msgstr "Привет"

      Но PO файл при неподходящей его настройке может содержать какой-то такой путь:

      #: themes/my-theme/js/scripts.js:9
      msgid "Hello"
      msgstr "Привет"

      В этом случае конечно не совпадет хэш и файл перевода не будет подключен.

      Вообще все это чудовищно...

      Да есть такое, но если все делать через WP-CLI, то такой проблемы не возникает и все получается довольно удобно.

      Ответить25 дней назад #