Getting Started with Localization & Translation

Thank you for helping translate XMCL! This guide covers everything you need to know about setting up your development workspace, navigating localization files, configuring your code editor (VS Code, Zed Editor, Neovim, JetBrains), testing your translations locally, and submitting a Pull Request.

---

1. Prerequisites

Before starting, ensure you have the following tools installed on your system:

• Git — Essential for cloning the repository and managing branches.
• Node.js (v18+ or v20+) — Required to build and run XMCL locally.
• pnpm — XMCL uses pnpm workspace package management. Enable it using Corepack:

  corepack enable

• Code Editor of your choice:
  • VS Code (with i18n-ally extension)
  • Zed Editor (high performance Rust editor)
  • Neovim / Vim (with yamlls LSP)
  • JetBrains IDEs (WebStorm / IntelliJ IDEA)

---

2. Repository Setup (Fork & Clone)

1. Fork the Repository: Visit the XMCL GitHub Repository and click Fork.
2. Clone with Submodules: You must use the --recurse-submodules flag to fetch necessary submodules:

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

   If you forgot to add --recurse-submodules, initialize them manually:

   git submodule update --init --recursive

3. Install Dependencies:

   pnpm install

---

3. Localization Architecture in XMCL

XMCL stores translations in YAML files across two primary modules:

x-minecraft-launcher
 ├─ 📂 xmcl-keystone-ui/locales/       # UI strings (buttons, tabs, dialogs)
 │   ├─ 📜 en.yaml                     # English (canonical reference)
 │   ├─ 📜 uk.yaml                     # Ukrainian
 │   └─ 📜 <locale-code>.yaml
 └─ 📂 xmcl-electron-app/main/locales/ # Main process strings (tray, notifications, errors)
     ├─ 📜 en.yaml
     ├─ 📜 uk.yaml
     └─ 📜 <locale-code>.yaml

---

4. Code Editors Setup Guide

Choose your preferred code editor below for the best translation experience:

VS Code

### Visual Studio Code Setup

VS Code provides dedicated UI tools for i18n translation key management.

1. Install the **i18n Ally** extension (`lokalise.i18n-ally`).
2. Open the project folder in VS Code.
3. In the sidebar, click the **i18n Ally** icon:
   - **Progress Tab**: View missing keys and completion percentage for all languages.
   - **Inline Translations**: Edit translations directly alongside code comments in `.vue` and `.ts` files.
4. Open `en.yaml` and your target language file (e.g. `uk.yaml`) side-by-side (`Ctrl+\` or `Cmd+\`).

Zed Editor

### Zed Editor Setup

Zed is a fast, GPU-accelerated editor built in Rust. It natively integrates with YAML Language Server (`yaml-lsp`).

1. **Install Extensions**: Open Zed Extensions (`Cmd+Shift+X` / `Ctrl+Shift+X`) and install `YAML` and `Vue`.
2. **Split-Pane Translation Workflow**:
   - Open `xmcl-keystone-ui/locales/en.yaml`.
   - Open a split pane (`Cmd+Shift+E` / `Ctrl+Shift+E` or right-click editor tab -> Split Right).
   - Open your target language file (e.g. `uk.yaml`).
3. **LSP Auto-completion**: Zed provides instant key completion and syntax validation via `yamlls`.

Neovim (NVIM)

" Neovim (NVIM) Setup

" Neovim setup using nvim-lspconfig and yamlls

" 1. Configure yamlls in your init.lua / lspconfig:
" require('lspconfig').yamlls.setup({
"   settings = {
"     yaml = {
"       validate = true,
"       completion = true
"     }
"   }
" })

" 2. Side-by-Side Buffer Splitting:
" Open English reference file and split vertically with your target locale:
:e xmcl-keystone-ui/locales/en.yaml
:vsplit xmcl-keystone-ui/locales/uk.yaml

" 3. Synchronized Scrolling:
" Lock scroll position between English and target translation buffers:
:set scrollbind

" 4. Recommended Plugins:
" - neovim/nvim-lspconfig & hrsh7th/nvim-cmp (YAML completion)
" - i18n-ally.nvim or vim-i18n (inline key resolution)

JetBrains / WebStorm

### JetBrains IDEs (WebStorm / IntelliJ IDEA)

1. Install the **i18n Ally** plugin from JetBrains Marketplace.
2. Open `en.yaml` and your locale `.yaml` file.
3. Right-click editor tab -> **Split Right** for side-by-side editing.
4. Use `Ctrl+F` / `Cmd+F` to search for keys matching the English reference file.

---

5. Adding a New Language

If your language is not yet registered in XMCL:

1. Register Language Code in locales.json: Open assets/locales.json and add your locale entry:

   {
     "zh-CN": "简体中文",
     "en": "English",
     "uk": "Українська",
     "fr": "Français"  // <-- Add new language entry
   }

2. Create New YAML Files: Create a new .yaml file using your locale code in both locale folders:
   • xmcl-keystone-ui/locales/fr.yaml
   • xmcl-electron-app/main/locales/fr.yaml
3. Populate Translations: Copy keys from en.yaml and translate the values into your target language.

---

6. Testing Your Translation Locally

1. Ensure all dependencies are installed (pnpm install).
2. Run the development environment:

   pnpm dev

   (Or in VS Code, press F5 or go to Run and Debug -> select Electron: Main (launch)).
3. Once XMCL opens, go to Settings ⚙️ -> General -> Language and switch to your translated language to verify UI formatting and text wrapping!

---

7. Submitting Your Changes (Pull Request)

1. Create a new git branch:

   git checkout -b i18n/add-ukrainian-translation

2. Commit your changes:

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

3. Push to your GitHub fork:

   git push origin i18n/add-ukrainian-translation

4. Open a Pull Request (PR) on the x-minecraft-launcher repository!