В этой части мы сосредоточимся на том, как переводить тексты и значения в нашем пользовательском блоке Гутенберга. Мы используем WP-CLI для создания необходимых файлов, чтобы Гутенберг мог загружать наши переводы при переключении языка WordPress.
Прежде чем продолжить, вам необходимо установить WP CLI (интерфейс командной строки для WordPress). Если у вас его нет, просто следуйте инструкциям в WordPress Handbook for CLI.
Кратко объясним, как переводить сценарии Javascript (Gutenberg): WordPress требует .moфайлов для перевода файлов PHP, но для Javascript WordPress требуется .jsonфайл. Для каждого файла Javascript требуется один файл JSON для перевода. JSON должен быть определенного формата (WP CLI сгенерирует его для нас) с нашими переведенными строками. Нам нужен один файл JSON для каждого языка, на который мы хотим перевести.
Итак, что нам нужно сделать, это сначала добавить функции gettext (__()и т. д _e().) в наши файлы Javascript и сгенерировать файл PO, как обычно для нашей темы или плагина. Поскольку мы обернули тексты в наши файлы сценариев, например __(),, PO-файл должен иметь возможность включать их. Далее делаем перевод как обычно в наш PO-файл. И, наконец, мы используем WP CLI для извлечения необходимых строк из файла PO и создания файлов JSON для всех наших файлов Javascript.
Имейте в виду, что .po/ .mo-файлы вашей темы или плагина никогда не повлияют на ваши файлы Javascript, даже если они содержат переведенные строки из наших файлов Javascript.
Реализация перевода в Javascript
Первый шаг — обернуть все тексты в нашем файле Javascript внутри функций перевода. Если вы занимались переводом WordPress на PHP, вы, вероятно, хорошо знакомы с функциями __(), _e(), esc_html__()и так далее. В WordPress есть пакет wp.i18n, содержащий эти функции, которые работают точно так же, как в PHP.
Как и в случае с PHP, вам необходимо указать домен textdomain (имя/дескриптор). Это может быть все, что вы хотите, но делайте это кратко, так как вам, вероятно, придется печатать его очень часто. Для моей темы я настроил свой текстовый домен с доменом awhitepixel. Итак, в PHP я буду __('My string', 'awhitepixel')переводить строки, и это будет точно так же в файлах Javascript.
Давайте начнем редактировать наш файл Javascript. Сначала нам нужно деструктурировать функцию __и из пакета. Из-за природы React, скорее всего, вы будете в основном или, возможно, только использовать эту функцию._e``wp.i18n``__
const { __, _e } = wp.i18n;А затем нужно найти все наши захардкоженные тексты в файле Javascript и обновить их. Имейте в виду, что для функций __и _eтребуется контекст Javascript. Это означает, что когда мы вводим строки, например, значения свойств объекта, мы используем __()их сразу, но в качестве значений, например, свойств, нам нужно обернуть все внутри { }, чтобы обозначить, что это код Javascript.
Например наш registerBlockTypeс поддержкой перевода будет выглядеть так:
registerBlockType('awp/firstblock', {
title: __('My first block', 'awhitepixel'),
category: 'common',
icon: 'smiley',
description: __('Learning in progress', 'awhitepixel'),
keywords: [__('example', 'awhitepixel'), __('test', 'awhitepixel')],
attributes: {
...А что касается реквизита, т.е. в InspectorControls:
Оберните все тексты, которые вы хотите поддерживать для перевода, в __()и _e(). Если вы следовали этому руководству шаг за шагом, у вас не должно быть случаев, когда вам нужно использовать файлы _e(). Когда вы закончите, перекомпилируйте Javascript, и мы отойдем от Javascript.
Настройка файлов po и/или pot
Этот шаг немного отличается в зависимости от того, что вы уже сделали и настроили для своей темы или плагина. Возможно, вы пишете свои сценарии Gutenberg в новом и пустом плагине, который не был настроен для перевода PHP, или внутри темы, в которой уже зарегистрирован текстовый домен. У вас могут быть готовые файлы PO (и MO) или у вас может быть только файл POT. Я постараюсь охватить все базы.
В моей теме или плагине уже есть po(t)-файл
Если у вас уже есть PO- или POT-файл в вашем проекте, то, скорее всего, у вас тоже есть функция PHP load_theme_textdomain(), load_child_theme_textdomain()или где- load_plugin_textdomain()то в вашем коде. Убедитесь, что зарегистрированный домен совпадает с тем, который вы использовали в своих файлах Javascript.
Все, что вам нужно сделать, это загрузить файл PO для языка, который вы хотите перевести (или создать его из файла POT), например, в PoEdit. Нажмите «Обновить из кода» (или аналогичную в других программах), чтобы программа могла сканировать все файлы проекта (включая наши недавно обновленные файлы Javascript) и обновить пул строк для перевода. Должны появиться строки в нашем файле Javascript. Затем вам просто нужно перевести их как обычно и сохранить.
PS: Если вы не можете нажать «Обновить из кода» или повторно отсканировать файлы, возможно, PO-файл настроен неправильно. Ищите советы в следующем разделе.
у меня нет файлов перевода
Если ваша тема или проект не настроены с переводом, вам нужно либо сгенерировать файл POT с помощью WP-CLI, либо вручную создать файл PO.
У меня есть подробное руководство по созданию PO-файла в моем Учебнике по теме для начинающих — часть 8. В посте описывается, как создать файл и правильно настроить его для поиска файлов тем, а также ключевые слова для поиска (__, _e, и т. д.).
Если вы хотите создать POT-файл, вы можете использовать команду wp i18n make-pot в WP-CLI, а затем создать из него PO-файл, используя, например, PoEdit. Имейте в виду, что вам нужно будет регенерировать файл POT (а затем файл PO) каждый раз, когда вы обновляете какие-либо строки в своем коде.
Конечный результат
Что вам в конечном итоге нужно, так это PO-файл, который нашел ваши строки Javascript, где они были переведены. Я рекомендую размещать ваши файлы перевода в отдельной папке в вашей теме или плагине. Когда мы начнем создавать файлы JSON, у нас будет довольно много файлов для перевода, и было бы неплохо хранить их все вместе в отдельной папке.
В качестве ориентира я помещаю все файлы перевода в свой theme/assets/lang/. Я добавил норвежский перевод для своей темы с именем nb_NO.po, который содержит переведенные строки из нашего файла Javascript пользовательского блока.
Создание файлов JSON из файла po
Следующим шагом будет использование WP-CLI для создания файлов JSON из нашего po-файла. Для этого используем команду wp i18n make-json.
Имейте в виду, что по умолчанию эта команда берет переведенные строки из вашего PO-файла для использования при создании JSON-файла. Это может быть обременительно в процессе разработки вашей темы или плагина. Потому что, когда вы добавляете новые или корректируете строки, вам придется повторно сканировать файлы и снова переводить все строки (и снова, и снова). К счастью, в команде есть флаг, чтобы избежать этого.
Давайте начнем! В терминале перейдите в языковую директорию вашего проекта. Запустите следующую команду и обратитесь к вашему po-файлу (как уже упоминалось, у меня есть nb_NO.poготовый файл).
wp i18n make-json nb_NO.po --no-purgeЕсли у вас нет проблем с удалением переведенных строк из вашего PO-файла (например, если вы делаете окончательную сборку), вы можете пропустить --no-purgeфлаг.
Терминал должен сообщить «Успех» и указать, сколько файлов JSON было создано. Если вы видите, что он сгенерировал два файла JSON, это потому, что он прочитал и наш файл исходного кода Javascript, и файл сборки, и сгенерировал по одному для каждого. Если в вашем проекте больше файлов Javascript, вы получите еще больше файлов JSON.
На момент написания этой статьи (WordPress v 5.3.2 и WP-CLI версии 2.4.0) файлы JSON генерируются с кодом языка и хэшем — загадочной строкой в качестве имен файлов. Нам нужно найти правильный и переименовать его.
Переименование файла JSON и загрузка его в PHP
Ваша языковая папка, вероятно, выглядит примерно так:
Помните, что команда сгенерировала один файл JSON для каждого файла Javascript, а поскольку у нас действительно есть два файла для нашего пользовательского блока (исходный код и сборка), она сгенерировала два файла. Если ваш код Javascript разбит на несколько файлов, каждый из них получит два собственных файла JSON.
Если у вас есть только два файла JSON (поскольку других файлов Javascript не найдено), вы можете удалить один из них сейчас. Если у вас их больше двух, вам нужно открыть файлы JSON и посмотреть, для какого файла они предназначены. Файлы JSON содержат свойство «source», которое сообщает вам, для какого файла Javascript этот файл JSON. Используйте это, чтобы выяснить, какой файл JSON сохранить. Я рекомендую найти окончательный файл сборки (в отличие от файлов разработки), так как он должен содержать все строки из всех файлов.
Когда вы нашли правильный, нам нужно переименовать его. Нам нужно переименовать его, чтобы следовать этому шаблону:
[textdomain]-[language code]-[script handle].json
Используйте текстовый домен, который вы использовали везде (например __('My string', 'awhitepixel')), добавьте тире и код языка. Затем укажите тире и дескриптор сценария, который вы использовали для регистрации файла Javascript Gutenberg (wp_register_script()). Для справки: мой текстовый домен — awhitepixel, мой языковой код — nb_NO, а мой дескриптор сценария для сценария Гутенберга — awp-myfirstblock-js. Поэтому я переименовываю файл JSON в:
awhitepixel-nb_NO-awp-myfirstblock-js.json
Скажите WordPress загрузить наш JSON
Все, что осталось, — это последний шаг — сказать WordPress загрузить наш файл JSON. Нам нужно использовать функцию [wp_set_script_translations](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)(). Это довольно новая функция WordPress, поэтому я рекомендую обернуть ее внутри файла function_exists(). Он принимает три параметра; дескриптор сценария для нашего блока, текстовый домен и путь к нашей папке перевода (примечание: путь, а не URL-адрес).
Внутри нашей функции, подключенной к init, где мы зарегистрировали наш блочный скрипт и вызов register_block_type, мы также можем вызвать эту новую функцию для загрузки нашего файла перевода JSON. PS: Имейте в виду, что хук enqueue_block_assetsне будет работать для регистрации переводов.
add_action('init', function() {
wp_register_script('awp-myfirstblock-js', ....);
register_block_type('awp/firstblock', ....
if (function_exists('wp_set_script_translations')) {
wp_set_script_translations('awp-myfirstblock-js', 'awhitepixel', get_template_directory(). '/assets/lang');
}
});И это все! Теперь ваш блок должен быть переведен. Переключите язык WordPress на язык, на который вы перевели, и проверьте его сами. Когда я переключаю свой язык WordPress на норвежский и добавляю свой блок, имя и все, что внутри него, переводится:
