Primeiros Passos com Localização & Tradução

Obrigado por ajudar a traduzir o X Minecraft Launcher (XMCL)! Este guia cobre tudo o que você precisa saber sobre como configurar seu ambiente de desenvolvimento, navegar pelos arquivos de localização, configurar seu editor de código (VS Code, Zed Editor, Neovim, JetBrains), testar suas traduções localmente e enviar um Pull Request.

---

1. Pré-requisitos

Antes de começar, certifique-se de ter as seguintes ferramentas instaladas:

• Git — Essencial para clonar o repositório e gerenciar branches.
• Node.js (v18+ ou v20+) — Necessário para compilar e executar o XMCL localmente.
• pnpm — O XMCL usa gerenciamento de pacotes com workspace pnpm. Ative-o usando o Corepack:

  corepack enable

• Editor de código de sua preferência:
  • VS Code (com extensão i18n-ally)
  • Zed Editor (editor em Rust de alto desempenho)
  • Neovim / Vim (com LSP yamlls)
  • JetBrains IDEs (WebStorm / IntelliJ IDEA)

---

2. Configuração do Repositório (Fork & Clone)

1. Fork do Repositório: Visite o Repositório GitHub do XMCL e clique em Fork.
2. Clone com Submódulos: Você deve usar a flag --recurse-submodules para buscar os submódulos necessários:

   git clone --recurse-submodules https://github.com/seu-usuario/x-minecraft-launcher.git
   cd x-minecraft-launcher

   Se esqueceu de adicionar --recurse-submodules, inicialize-os manualmente:

   git submodule update --init --recursive

3. Instale as Dependências:

   pnpm install

---

3. Arquitetura de Localização no XMCL

O XMCL armazena traduções em arquivos YAML em dois módulos principais:

x-minecraft-launcher
 ├─ 📂 xmcl-keystone-ui/locales/       # Strings da UI (botões, abas, diálogos)
 │   ├─ 📜 en.yaml                     # Inglês (referência canônica)
 │   ├─ 📜 uk.yaml                     # Ucraniano
 │   └─ 📜 <código-locale>.yaml
 └─ 📂 xmcl-electron-app/main/locales/ # Strings do processo principal (bandeja, notificações, erros)
     ├─ 📜 en.yaml
     ├─ 📜 uk.yaml
     └─ 📜 <código-locale>.yaml

---

4. Guia de Configuração de Editores de Código

Escolha seu editor preferido abaixo para a melhor experiência de tradução:

VS Code

### Configuração do Visual Studio Code

O VS Code fornece ferramentas de UI dedicadas para gerenciamento de chaves de tradução i18n.

1. Instale a extensão **i18n Ally** (`lokalise.i18n-ally`).
2. Abra a pasta do projeto no VS Code.
3. Na barra lateral, clique no ícone do **i18n Ally**:
   - **Aba de Progresso**: Veja as chaves faltantes e a porcentagem de conclusão para todos os idiomas.
   - **Traduções Inline**: Edite traduções diretamente ao lado dos comentários de código nos arquivos `.vue` e `.ts`.
4. Abra `en.yaml` e o arquivo do seu idioma alvo (ex: `pt.yaml`) lado a lado (`Ctrl+\` ou `Cmd+\`).

Zed Editor

### Configuração do Zed Editor

O Zed é um editor rápido e acelerado por GPU construído em Rust. Integra-se nativamente com o YAML Language Server (`yaml-lsp`).

1. **Instale Extensões**: Abra as Extensões do Zed (`Cmd+Shift+X` / `Ctrl+Shift+X`) e instale `YAML` e `Vue`.
2. **Fluxo de Tradução com Painéis Divididos**:
   - Abra `xmcl-keystone-ui/locales/en.yaml`.
   - Abra um painel dividido (`Cmd+Shift+E` / `Ctrl+Shift+E` ou clique com botão direito na aba do editor -> Dividir à Direita).
   - Abra o arquivo do seu idioma alvo (ex: `pt.yaml`).
3. **Autocompletar LSP**: O Zed fornece completação de chaves instantânea e validação de sintaxe via `yamlls`.

Neovim (NVIM)

" Configuração do Neovim (NVIM)

" Configuração do Neovim usando nvim-lspconfig e yamlls

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

" 2. Divisão de Buffer Lado a Lado:
" Abra o arquivo de referência em inglês e divida verticalmente com seu locale alvo:
:e xmcl-keystone-ui/locales/en.yaml
:vsplit xmcl-keystone-ui/locales/pt.yaml

" 3. Rolagem Sincronizada:
" Bloqueie a posição de rolagem entre os buffers de tradução em inglês e alvo:
:set scrollbind

" 4. Plugins Recomendados:
" - neovim/nvim-lspconfig & hrsh7th/nvim-cmp (completação YAML)
" - i18n-ally.nvim ou vim-i18n (resolução de chaves inline)

JetBrains / WebStorm

### JetBrains IDEs (WebStorm / IntelliJ IDEA)

1. Instale o plugin **i18n Ally** do JetBrains Marketplace.
2. Abra `en.yaml` e o arquivo `.yaml` do seu locale.
3. Clique com botão direito na aba do editor -> **Dividir à Direita** para edição lado a lado.
4. Use `Ctrl+F` / `Cmd+F` para buscar chaves correspondentes ao arquivo de referência em inglês.

---

5. Adicionando um Novo Idioma

Se seu idioma ainda não está registrado no XMCL:

1. Registre o Código de Idioma em locales.json: Abra assets/locales.json e adicione sua entrada de locale:

   {
     "zh-CN": "简体中文",
     "en": "English",
     "pt": "Português (Brasil)",
     "fr": "Français"
   }

2. Crie Novos Arquivos YAML: Crie um novo arquivo .yaml usando seu código de locale em ambas as pastas de locale:
   • xmcl-keystone-ui/locales/pt.yaml
   • xmcl-electron-app/main/locales/pt.yaml
3. Preencha as Traduções: Copie as chaves de en.yaml e traduza os valores para o seu idioma alvo.

---

6. Testando Sua Tradução Localmente

1. Certifique-se de que todas as dependências estão instaladas (pnpm install).
2. Execute o ambiente de desenvolvimento:

   pnpm dev

   (Ou no VS Code, pressione F5 ou vá em Executar e Depurar -> selecione Electron: Main (launch)).
3. Assim que o XMCL abrir, vá em Configurações ⚙️ -> Geral -> Idioma e mude para o idioma traduzido para verificar a formatação da UI e a quebra de texto!

---

7. Enviando Suas Alterações (Pull Request)

1. Crie uma nova branch git:

   git checkout -b i18n/adicionar-traducao-portugues

2. Faça commit das suas alterações:

   git add .
   git commit -m "i18n: adicionar tradução em Português do Brasil"

3. Envie para o seu fork no GitHub:

   git push origin i18n/adicionar-traducao-portugues

4. Abra um Pull Request (PR) no repositório x-minecraft-launcher!