Функция wp_set_script_translations(): Локализация JavaScript в WordPress

Функция wp_set_script_translations() в WordPress используется для привязки строк перевода к JavaScript-файлу (скрипту) с помощью JSON-файлов локализации. Эта функция делает возможным использование функций локализации, таких как __(), _n(), _x(), и других прямо в JavaScript-коде.

wp_set_script_translations( string $handle, string $domain = 'default', string $path = '' ): bool

Параметры

• $handle (строка) – Обязательный. Уникальный идентификатор скрипта (handle), к которому будет прикреплен файл перевода.
• $domain (строка) – Необязательный. Текстовый домен, который будет использоваться для локализации. По умолчанию 'default'.
• $path (строка) – Необязательный. Полный путь к директории, где хранятся файлы перевода. Если не указан, WordPress будет искать файлы перевода в стандартной директории /wp-content/languages.

Возвращаемое значение

Функция возвращает true, если текстовый домен был успешно локализован, и false, если возникли ошибки.

Основные моменты

1. wp_set_script_translations() должна быть вызвана после регистрации или подключения скрипта с помощью wp_register_script() или wp_enqueue_script().
2. Если локализация используется для нескольких скриптов, необходимо вызвать wp_set_script_translations() для каждого скрипта отдельно.
3. Скрипт также становится зависимым от библиотеки wp-i18n, которая предоставляет функции для перевода строк в JavaScript.

Пример 1: Привязка локализации к JavaScript-файлу

add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

function my_enqueue_scripts() {
    // Регистрируем и добавляем скрипт в очередь
    wp_enqueue_script( 'my-custom-script', get_template_directory_uri() . '/js/custom-script.js', array(), '1.0.0', true );

    // Привязываем переводы к нашему скрипту
    wp_set_script_translations( 'my-custom-script', 'my-text-domain', get_template_directory() . '/languages/js' );
}

В данном примере мы:

• Регистрируем и добавляем в очередь скрипт custom-script.js.
• Указываем для него текстовый домен my-text-domain, который будет использоваться в функциях перевода.
• Путь к JSON-файлам перевода указывает на директорию /languages/js внутри темы.

Как использовать функции перевода в JavaScript

После успешной регистрации перевода для JavaScript файла можно использовать следующие функции в коде:

const { __, _x, _n, _nx } = wp.i18n;

jQuery(document).ready(function($) {
    console.log( __( 'Hello', 'my-text-domain' ) ); // Выведет 'Привет' на русском, если перевод существует
    console.log( _x( 'Link', 'short label', 'my-text-domain' ) );
    console.log( _n( '%s comment', '%s comments', 2, 'my-text-domain' ) );
});

Пример 2: Создание файла перевода через WP-CLI

Если вам нужно сгенерировать JSON-файлы для перевода, используйте WP-CLI. Перейдите в директорию вашего плагина и выполните команду:

wp i18n make-json languages

Это создаст необходимые файлы локализации для JavaScript, которые можно использовать с wp_set_script_translations().

После этого вы можете настроить локализацию в коде плагина следующим образом:

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script( 'my-plugin-script', plugin_dir_url( __FILE__ ) . 'js/plugin-script.js', array(), '1.0.0', true );
    wp_set_script_translations( 'my-plugin-script', 'my-plugin-domain', plugin_dir_path( __FILE__ ) . 'languages' );
});

Пример 3: Формат JSON-файла переводов

Пример файла перевода ru_RU.json:

{
    "translation-revision-date": "2024-10-01 00:00:00+0000",
    "generator": "GlotPress/3.0.0",
    "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 comment": [ "%s comment", "%s комментарий", "%s комментария", "%s комментариев" ]
        }
    }
}

Этот JSON-файл содержит строки перевода, которые будут использоваться для локализации JavaScript.

Важные моменты

• Если третьим аргументом передается путь к файлу локализации, WordPress будет искать файлы перевода в указанной директории.
• Хэш MD5 добавляется к имени JSON-файла, если путь к скрипту содержит дополнительные каталоги.
• Локализация через wp_set_script_translations() добавляет зависимость от библиотеки wp-i18n, которая автоматически подключается WordPress.

Заключение

Функция wp_set_script_translations() — это эффективный инструмент для локализации JavaScript в WordPress. Она позволяет разработчикам легко управлять переводами строк в JavaScript и улучшать пользовательский опыт для международных аудиторий.