uk CONTRIBUTING I18n

Внесок у переклади

SelenaCore постачається 16 мовами (2 — людиною, 14 — машиною). Цей документ пояснює, як покращити вже наявний переклад і як запропонувати нову мову.

Рівні (tiers) у двох словах

Кожна цільова мова збирається з до чотирьох файлів, за пріоритетом:

src/i18n/locales/{lang}.ts             ← ручний (найвищий)
src/i18n/locales/{lang}.community.json ← виправлення спільноти
src/i18n/locales/auto/{lang}.auto.json ← згенероване машиною (найнижчий)
src/i18n/locales/en.ts                 ← англійський запасний

Коли ви відкриваєте UI польською, i18next зливає їх зліва направо: ручне має пріоритет над community, community — над auto. en.ts закриває все, чого немає в цільовій мові.

Така ж ієрархія у віджетів / сторінок налаштувань системних модулів (system_modules/*/locales/{lang}.{auto,community}.json) та спільних рядків через /api/i18n/bundle/*.

Покращення машинно перекладеної мови

Це найчастіший внесок. Argos робить основну частину перекладу, але ламається на крайніх випадках (одиниці часу, відмінювання, багатозначні технічні терміни). Ви виправляєте їх, не чіпаючи .auto.json напряму.

Процес

1. Форкніть репозиторій SelenaCore.

2. Знайдіть проблемні ключі. Відкрийте UI цільовою мовою і помітьте, що читається дивно. Файл auto.json містить машинні переклади — корисний як довідник.

3. Створіть community-override. У src/i18n/locales/ створіть {lang}.community.json:

   {
       "layout.total": "{{count}} łącznie",
       "integrityPage.metaLine": "SHA256 · {{checks}} kontroli · co 30 s"
   }

   Використовуйте ті самі flat-ключі, що в en.ts (вкладені ключі склеєні крапкою: layout.total).

   Не треба перекладати кожен ключ — усе, що не включено, відкочується на auto-рівень. Почніть із 10-20 ключів, які найбільше дратують.

4. Зберігайте плейсхолдери. {{count}}, {{name}}, {{lang}} тощо мають з'являтися у вашому перекладі точно так само, як в англійській версії.

5. Перевіряйте форми множини. Ключі з суфіксами _one, _few, _many, _other — це CLDR-варіанти, які використовуються коли {{count}} вимагає різної граматики. Для слов'янських мов (ru, pl, cs, uk) їх чотири. Якщо виправляєте одну форму — виправте всі для цього ключа.

6. Локальна перевірка.

   python scripts/i18n_diff.py

7. Відкрийте PR з назвою i18n({lang}): <що виправили>.

Badge про community-внесок

Коли для мови існує .community.json, у LanguagePicker поряд із нею показується бейдж "Community-improved".

Додавання нової мови

1. Відкрийте Language request issue.

2. Наступний запуск CI автоматично згенерує {code}.auto.json.

3. Полірують через {code}.community.json як описано вище.

Що НЕ робити

• Не редагуйте {lang}.auto.json напряму. Перегенерується CI при кожній зміні en.ts — ваші правки затруться.

• Не перекладайте технічні терміни з глосарія. SHA256, Piper, Ollama, Bluetooth тощо зберігаються як є. Якщо вважаєте, що термін ПОВИНЕН перекладатись (як Provider → Anbieter в німецькій), додайте його до per_language_overrides у src/i18n/glossary.json, а не у community-файл.

• Не вигадуйте нові ключі. Якщо немає в en.ts — UI не використає. Для нових ключів потрібна окрема PR на англійське джерело.

Локальні перевірки

# Відповідність ключів між en.ts та всіма manual-tier файлами
python scripts/i18n_diff.py

# Сканер хардкодних рядків, які пропустили i18n
python scripts/i18n_audit.py

# Лінт-гейт CI (parity + baseline хардкодів)
python scripts/i18n_lint.py

Запитання

Відкрийте обговорення на GitHub або пінґніть майнтейнера в issue — tooling для перекладів ще молодий, і ми раді доопрацьовувати workflow на основі реального фідбеку.