У цій частині ми зосередимося на тому, як перекладати тексти та значення в нашому спеціальному блоці Гутенберга. Ми використовуємо 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, вам потрібно надати текстовий домен (ім’я/дескриптор). Це може бути все, що завгодно, але будьте короткими, оскільки вам, імовірно, доведеться вводити його дуже часто. Для моєї теми я налаштував текстовий домен із доменом awhitepixel. Тож у PHP я зроблю __('My string', 'awhitepixel')переклад рядків, і це буде точно так само у файлах Javascript.
Давайте почнемо редагувати наш файл Javascript. Спочатку нам потрібно деструктурувати функцію __і _eз wp.i18nпакета. Через природу React, швидше за все, ви будете використовувати в основному або, можливо, лише цю __функцію.
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:
<InspectorControls>
<PanelBody
title={__("Most awesome settings ever", 'awhitepixel')}
initialOpen={true}
>
...
<ToggleControl
label={__("Toggle me", 'awhitepixel')}
checked={attributes.toggle}
onChange={(newval) => setAttributes({ toggle: newval })}
/>
...Обгорніть усі тексти, переклад яких потрібно підтримувати, мовами __()та _e(). Якщо ви дотримувалися цього підручника крок за кроком, у вас не повинно бути випадків, коли вам потрібно буде використовувати _e(). Коли ви закінчите, перекомпілюйте Javascript, і ми відійдемо від Javascript.
Налаштування файлів po та/або pot
Цей крок дещо відрізняється залежно від того, що ви вже зробили та налаштували для своєї теми чи плагіна. Можливо, ви пишете свої сценарії Gutenberg у новому порожньому плагіні, який не налаштовано для перекладу PHP, або в темі, для якої вже зареєстровано текстовий домен. У вас можуть бути готові файли PO (і MO) або ви можете мати лише файл POT. Я докладу всіх зусиль, щоб охопити всі основи.
Моя тема або плагін уже має po(t)-файл
Якщо у вашому проекті вже є PO- або POT-файл, швидше за все, у вас також є функція PHP load_theme_textdomain()або десь у вашому коді. Переконайтеся, що зареєстрований домен збігається з тим, який ви використовували у своїх файлах Javascript.load_child_theme_textdomain()``load_plugin_textdomain()
Все, що вам потрібно зробити, це завантажити файл PO для мови, яку ви хочете перекласти (або створити його з файлу POT), наприклад, у PoEdit. Натисніть «Оновити з коду» (або подібне в інших програмах), щоб програма могла просканувати всі файли проекту (включно з нашими нещодавно оновленими файлами Javascript) і оновити пул рядків для перекладу. Рядки в нашому файлі Javascript мають з’явитися. Потім вам просто потрібно перекласти їх як звичайні та зберегти.
PS: якщо ви не можете натиснути «Оновити з коду» або повторно просканувати файли, можливо, PO-файл налаштовано неправильно. Шукайте поради в наступному розділі.
У мене немає файлів перекладу
Якщо у вашій темі чи проекті не налаштовано переклад, вам потрібно створити POT-файл за допомогою WP-CLI або створити POT-файл вручну.
У моїй тематичній підручнику для початківців – частина 8 я маю докладний посібник із створення PO-файлу. У дописі описано, як створити файл і правильно налаштувати його для пошуку у файлах теми, а також ключові слова для пошуку (__, _eтощо).
Якщо ви бажаєте створити POT-файл, ви можете скористатися командою wp i18n make-pot у WP-CLI, а потім створити з нього POT-файл, наприклад, 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 для кожного файлу Javascript – і оскільки ми фактично маємо два файли для нашого спеціального блоку (джерело та збірка), вона згенерувала два файли. Якщо ваш код Javascript розділити на кілька файлів, кожен отримає два власні файли JSON.
Якщо у вас є лише два файли JSON (оскільки інших файлів Javascript не знайдено), ви можете видалити один із них зараз. Якщо у вас більше двох, вам потрібно відкрити файли JSON і подивитися, для якого файлу вони призначені. Файли JSON містять властивість «source», яка повідомляє, для якого файлу Javascript цей файл JSON. Використовуйте це, щоб визначити, який файл JSON зберегти. Я рекомендую знайти остаточний файл збірки (на відміну від файлів dev), оскільки він має містити всі рядки з усіх файлів.
Коли ви знайдете правильний, нам потрібно його перейменувати. Нам потрібно перейменувати його відповідно до цього шаблону:
[textdomain]-[language code]-[script handle].json
Використовуйте текстовий домен, який ви використовували всюди (наприклад __('My string', 'awhitepixel'),), додайте тире та код мови. Потім введіть тире та дескриптор сценарію, який ви використовували для реєстрації свого файлу Gutenberg Javascript (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 на норвезьку та додаю свій блок, ім’я та все в ньому перекладається:
