# Переклади

Blockstudio постачається з перекладами в каталозі `languages`. WordPress використовує їх, коли мова сайту або мова в профілі користувача збігається з однією з них. Це працює однаково, коли Blockstudio запускається як плагін, обов’язковий до використання плагін або пакет Composer.

## Доступні мови

Blockstudio містить переклади для WordPress локалей, зазначених у вбудованому `languages/locales.json`, зокрема регіональні варіанти та варіанти з формальним і неформальним звертанням. Англійська (`en_US`) — мова оригіналу, тому файл перекладу для неї не потрібен. Список поєднує локалі, які підтримує WordPress у GlotPress, із варіантами, доступними у WordPress основному перекладі API.

Наявні переклади німецькою (`de_DE`) та формальною німецькою (`de_DE_formal`) збережено. Додаткові переклади згенеровано за допомогою GPT-6 Luna і позначено як машинні у заголовках `.po`. Вони пройшли автоматичні перевірки повноти й формату, але не всі їх перевірили носії мови. Будемо вдячні за виправлення.

Переклади охоплюють елементи керування полями в редакторі блоків, сторінку адміністратора, полотно, накладку devtools і повідомлення кінцевих точок REST. Мітки й довідкові тексти у власних файлах `block.json` належать вашій темі або плагіну та використовують його текстовий домен.

Виберіть мову в **Налаштування > Загальні > Мова сайту** або вкажіть особисту мову у своєму профілі WordPress. Blockstudio автоматично використовує вибрану локаль. Він не додає мов до списку вибору мов у WordPress: локаль також має бути доступна у вашій інсталяції WordPress. На вашому сайті не потрібні запити до ШІ, передплата на переклади чи додаткові налаштування середовища виконання.

## Перевизначення перекладу

Файли перекладу в `wp-content/languages/plugins` мають вищий пріоритет за вбудовані файли як для рядків PHP (`blockstudio-de_DE.mo` або `blockstudio-de_DE.l10n.php`), так і для скриптів (окремий файл для кожного дескриптора скрипту, наприклад `blockstudio-de_DE-blockstudio-blocks.json`).

## Як долучитися до перекладу

Кожна мова — це файл `.po`, який можна редагувати в будь-якому текстовому редакторі або за допомогою інструмента перекладу, наприклад Poedit. Будемо раді виправленням і новим мовам у вигляді pull request.

1. Щоб додати мову, скопіюйте `languages/blockstudio.pot` у `languages/blockstudio-<locale>.po`, наприклад `blockstudio-fr_FR.po`, і заповніть заголовки `Language` та `Plural-Forms`. Щоб покращити переклад, відредагуйте наявний файл `.po`.
2. Перекладіть рядки. Залишайте в перекладі заповнювачі, як-от `%1$s`.
3. Запустіть `npm run i18n`. Він створить файли `.mo`, `.l10n.php` і `.json`, які завантажує WordPress.
4. Додайте файл `.po` разом зі згенерованими файлами до коміту та створіть pull request.

Якщо ви не можете запустити `npm`, достатньо створити pull request лише з файлом `.po`. Згенеровані файли можна додати до злиття.

## Створення відсутніх перекладів

Підтримувачі можуть згенерувати відсутні рядки за допомогою автентифікованого Codex CLI. Це необов’язкова команда для розробки, яку WordPress не запускає:

```bash
npm run i18n:translate -- --dry-run
npm run i18n:translate
```

Модель за замовчуванням — `gpt-6-luna`. Щоб працювати з однією локаллю, скористайтеся `npm run i18n:translate -- --locale fr_FR`. Команда витягує найновіші вихідні рядки, заповнює відсутні переклади, а потім компілює файли `.mo`, `.l10n.php` і `.json` для кожного скрипту. До Codex надсилаються лише загальнодоступні рядки інтерфейсу, їхній контекст і наявні форми, а не вміст сайту чи дані користувачів.

Наявні непорожні переклади ніколи не замінюються. Завершені пакети зберігаються, тож після переривання можна запустити команду знову, щоб продовжити роботу з відсутніми перекладами. Перед збереженням перевіряються заповнювачі, як-от `%1$s`, розмітка HTML, технічні ідентифікатори та обов’язкові форми множини. Нечіткі записи й змінені вихідні форми множини залишаються на перевірку перекладачу. Якщо запитана модель недоступна, підміна іншою моделлю не використовується.

`npm run i18n:locales` явно оновлює список локалей і правила множини з WordPress/GlotPress. `npm run i18n:coverage` перевіряє, чи завершено переклад для кожної локалі зі списку в репозиторії. Перевірки повноти й звичайний CI не викликають ШІ та не отримують дані про локалі. Варіанти пакетної обробки, паралельного виконання та відновлення описано в README репозиторію.

## Рядки коду, які можна перекладати

- PHP: використовуйте функції WordPress із текстовим доменом `blockstudio`, наприклад `__( 'Invalid block.', 'blockstudio' )`.
- JavaScript: імпортуйте `__` з `@/utils/__` і передайте літеральний рядок, наприклад `__( 'Add row' )`. Рядок, сформований під час виконання програми, перекласти неможливо, тому використовуйте окремий літеральний рядок для кожного варіанта.
- Для нового пакета скриптів із рядками для перекладу потрібен запис у `scripts/i18n.ts` і виклик `wp_set_script_translations()` із тим самим ідентифікатором і `Translations::script_path()`.

Після зміни рядків запустіть `npm run i18n`. Команда оновить `languages/blockstudio.pot` і кожен файл `.po`. Нові рядки залишаються англійською, доки перекладач або `npm run i18n:translate` не заповнить їх. CI запускає `npm run i18n:check` і `npm run i18n:coverage`, які виявляють застарілі скомпільовані файли, проблеми з вилученням рядків або неповне покриття локалями. Генерація залишається явною дією супроводжувача.