Початок роботи з локалізацією та перекладом

Дякуємо за допомогу у перекладі XMCL! Цей посібник охоплює все необхідне для налаштування робочого середовища, роботи з файлами локалізації, налаштування ваших улюблених редакторів коду (VS Code, Zed Editor, Neovim, JetBrains), локального тестування та відправки Pull Request.

---

1. Попередні вимоги

Перед початком перевірте наявність таких інструментів на вашому комп'ютері:

• Git — необхідний для клонування репозиторію та керування гілками.
• Node.js (версія v18+ або v20+) — потрібен для збірки та запуску XMCL.
• pnpm — XMCL використовує менеджер пакетів pnpm. Увімкніть його через Corepack:

  corepack enable

• Редактор коду на ваш вибір:
  • VS Code (з розширенням i18n-ally)
  • Zed Editor (швидкий редактор на Rust)
  • Neovim / Vim (з yamlls LSP)
  • JetBrains IDEs (WebStorm / IntelliJ IDEA)

---

2. Налаштування репозиторію (Fork & Clone)

1. Зробіть Fork: Перейдіть до репозиторію XMCL на GitHub та натисніть Fork.
2. Клонуйте з сабмодулями: Ви обов'язково повинні використати прапор --recurse-submodules:

   git clone --recurse-submodules https://github.com/your-username/x-minecraft-launcher.git
   cd x-minecraft-launcher

   Якщо ви забули вказати прапор, ініціалізуйте сабмодулі вручну:

   git submodule update --init --recursive

3. Встановіть залежності:

   pnpm install

---

3. Архітектура локалізації XMCL

XMCL зберігає переклади у файлах YAML у двох основних модулях:

x-minecraft-launcher
 ├─ 📂 xmcl-keystone-ui/locales/       # Рядки інтерфейсу (кнопки, вкладки, діалоги)
 │   ├─ 📜 en.yaml                     # Англійська мова (еталонний зразок)
 │   ├─ 📜 uk.yaml                     # Українська мова
 │   └─ 📜 <код-мови>.yaml
 └─ 📂 xmcl-electron-app/main/locales/ # Рядки головного процесу (трей, сповіщення, помилки)
     ├─ 📜 en.yaml
     ├─ 📜 uk.yaml
     └─ 📜 <код-мови>.yaml

---

4. Налаштування редакторів коду

Оберіть свій редактор коду для зручної роботи з перекладом:

VS Code

### Налаштування Visual Studio Code

VS Code надає графічний інтерфейс для зручного перекладу ключів i18n.

1. Встановіть розширення **i18n Ally** (`lokalise.i18n-ally`).
2. Відкрийте папку проекту у VS Code.
3. На бічній панелі натисніть іконку **i18n Ally**:
   - **Progress Tab**: перегляд прогресу перекладу та відсутніх ключів.
   - **Inline Translations**: редагування перекладів безпосередньо в коді `.vue` та `.ts`.
4. Відкрийте `en.yaml` та файл вашої мови (наприклад, `uk.yaml`) поруч (`Ctrl+\` або `Cmd+\`).

Zed Editor

### Налаштування Zed Editor

Zed — це надшвидкий редактор на Rust з нативною підтримкою YAML Language Server (`yaml-lsp`).

1. **Встановіть розширення**: Натисніть `Cmd+Shift+X` / `Ctrl+Shift+X` та встановіть `YAML` та `Vue`.
2. **Розділений вигляд для перекладу**:
   - Відкрийте `xmcl-keystone-ui/locales/en.yaml`.
   - Розділіть панель (`Cmd+Shift+E` / `Ctrl+Shift+E` або клацніть правою кнопкою на вкладку -> Split Right).
   - Відкрийте файл вашої мови (наприклад, `uk.yaml`).
3. **Автодоповнення LSP**: Zed автоматично підказує ключі та перевіряє синтаксис YAML через `yamlls`.

Neovim (NVIM)

" Налаштування Neovim (NVIM)

" Конфігурація yamlls через nvim-lspconfig:

" 1. Налаштуйте yamlls у вашому init.lua:
" require('lspconfig').yamlls.setup({
"   settings = {
"     yaml = {
"       validate = true,
"       completion = true
"     }
"   }
" })

" 2. Розділення буферів (Side-by-Side):
" Відкрийте англійський еталон та розділіть вертикально з вашою мовою:
:e xmcl-keystone-ui/locales/en.yaml
:vsplit xmcl-keystone-ui/locales/uk.yaml

" 3. Синхронна прокрутка (Scrollbind):
" Зафіксуйте прокрутку між двома буферами:
:set scrollbind

" 4. Рекомендовані плагіни:
" - neovim/nvim-lspconfig та hrsh7th/nvim-cmp (підказки YAML)
" - i18n-ally.nvim або vim-i18n (відображення значення ключів у коді)

JetBrains / WebStorm

### Налаштування JetBrains IDEs (WebStorm / IntelliJ IDEA)

1. Встановіть плагін **i18n Ally** з JetBrains Marketplace.
2. Відкрийте `en.yaml` та файл вашої мови.
3. Клацніть правою кнопкою миші на вкладку -> **Split Right** для розділеного перегляду.
4. Використовуйте `Ctrl+F` / `Cmd+F` для пошуку потрібних ключів.

---

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

Якщо вашої мови ще немає у XMCL:

1. Зареєструйте код мови в locales.json: Відкрийте assets/locales.json та додайте новий рядок:

   {
     "zh-CN": "简体中文",
     "en": "English",
     "uk": "Українська",
     "fr": "Français"  // <-- Додано нову мову
   }

2. Створіть нові файли YAML: Створіть файли з кодом вашої мови у двох папках:
   • xmcl-keystone-ui/locales/fr.yaml
   • xmcl-electron-app/main/locales/fr.yaml
3. Заповніть переклад: Скопіюйте ключі з en.yaml та перекладіть їх значення.

---

6. Локальне тестування перекладу

1. Переконайтеся, що всі залежності встановлені (pnpm install).
2. Запустіть лаунчер у режиме розробки:

   pnpm dev

   (Або у VS Code натисніть F5 -> Run and Debug -> Electron: Main (launch)).
3. У відкритому лаунчері перейдіть до Налаштування ⚙️ -> Загальні -> Мова та виберіть вашу мову для перевірки відображення тексту!

---

7. Відправка змін (Pull Request)

1. Створіть нову гілку в git:

   git checkout -b i18n/add-ukrainian-translation

2. Збережіть зміни:

   git add .
   git commit -m "i18n: add Ukrainian translation"

3. Відправте гілку на ваш GitHub fork:

   git push origin i18n/add-ukrainian-translation

4. Відкрийте Pull Request (PR) у головному репозиторії x-minecraft-launcher!