WP_SET_SCRIPT_TRANSLATIONS() │ WP 5.0.0

Функция wp_set_script_translations() используется для установки переведённых строк для скрипта. Она работает только в том случае, если скрипт уже был зарегистрирован.

Используемые функции

• WP_Scripts::set_translations()
• WP_Scripts::print_translations()
• load_script_textdomain()

Возврат значения

Функция возвращает:

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

Как использовать

Вот как выглядит использование функции:

wp_set_script_translations( $handle, $domain, $path );

Параметры

• $handle (string) (обязательный) - уникальный идентификатор скрипта, к которому будет прикреплён текстовый домен.
• $domain (string) - текстовый домен.
  • Значение по умолчанию: 'default'
• $path (string) - полный путь к директории, содержащей файлы перевода.
  • Значение по умолчанию: ''

Примеры

1. Подключение файла перевода 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' );
});

Важно:

• Убедитесь, что идентификатор (handle) одинаковый - 'my-script'.
• Вызовите wp_set_script_translations() после wp_enqueue_script().

Что делает этот код

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

Поиск файла перевода происходит в следующем порядке (файл должен, конечно, существовать):

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

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

Почитать, как создать JSON-файл перевода, можно в документации.

3. Подключает наш JS файл PATH_TO_THEMES/scripts.js в HTML.

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

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

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": ["Hello"],
            "%s stars": ["%s stars", "%s звезда", "%s звезды", "%s звёзд"],
            "short wordu0004Hi": ["Прив"],
            "superstarsu0004%s stars": ["%s stars", "%s суперзвезда", "%s суперзвезды", "%s суперзвёзд"]
        }
    }
}

3. Создание 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, язык не будет отображаться при использовании третьего аргумента.

Примечания

• Смотрите: WP_Scripts::set_translations()
• Глобально: WP_Scripts. $wp_scripts - объект WP_Scripts для отображения скриптов.

Изменения

• С версии 5.0.0 — введена функция.
• С версии 5.1.0 — параметр $domain стал необязательным.

Заключение

Функция wp_set_script_translations() позволяет легко управлять локализацией скриптов в ваших темах и плагинах, что делает ваш проект более доступным для пользователей разных языков.