Localização de apps iOS com String Catalogs do Xcode

A CLI da Lingo.dev traduz String Catalogs do Xcode (.xcstrings) por meio de uma engine de localização configurada. String Catalogs são o formato moderno de localização da Apple, introduzido no Xcode 15, que reúne todos os idiomas em um único arquivo JSON. A CLI atualiza esse arquivo no local, sem precisar de diretórios separados por idioma.

Este guia mostra como localizar um app iOS de ponta a ponta: configurar a CLI, traduzir localmente e automatizar com o GitHub App para que as traduções sejam enviadas a cada push.

Como funcionam os String Catalogs#

Antes do Xcode 15, a localização no iOS exigia gerenciar arquivos separados .strings e .stringsdict em diretórios [locale].lproj/. Os String Catalogs substituem essa estrutura por um único arquivo Localizable.xcstrings, mantido automaticamente pelo Xcode.

Quando você marca uma string como localizável no SwiftUI ou UIKit, o Xcode a detecta durante a build e adiciona uma entrada ao String Catalog. Cada entrada registra a string de origem, suas traduções para cada idioma configurado e um campo opcional de comentário que dá contexto aos tradutores.

A CLI detecta o formato .xcstrings pela extensão do arquivo, interpreta essa estrutura JSON, traduz cada entrada por meio do engine de localização e grava as traduções de volta no mesmo arquivo, preservando comentários, regras de plural e metadados.

Pré-requisitos#

node -v

Instale e configure a CLI#

Instale a CLI, faça a autenticação e depois configure o projeto. Consulte o Quickstart para ver o passo a passo completo.

npm install -g @lingo.dev/cli
lingo login

Execute lingo init na raiz do projeto e responda aos prompts (idioma de origem, idiomas de destino e o padrão de arquivo que aponta para seu String Catalog). Depois, execute lingo link para vincular o projeto à sua organização e ao seu engine. Juntos, eles geram um .lingo/config.json:

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "MyApp/Localizable.xcstrings" }]
}

Faça commit de .lingo/config.json — ele é a fonte da verdade sobre o que será traduzido. O formato .xcstrings é detectado pela extensão do arquivo. Como os String Catalogs armazenam todos os idiomas em um único arquivo, não é preciso usar placeholder de idioma no padrão: a CLI lê as entradas no idioma de origem e grava todos os idiomas de destino de volta no mesmo arquivo. Consulte a Referência de configuração para ver o schema completo.

{
  "files": [
    { "pattern": "MyApp/Localizable.xcstrings" },
    { "pattern": "MyAppWidgets/Localizable.xcstrings" }
  ]
}

Traduza localmente#

Na raiz do projeto, execute a primeira tradução:

lingo push --backfill-missing

A CLI lê seu String Catalog, traduz cada entrada ausente por meio do seu engine de localização, aguarda a execução terminar e grava os resultados de volta no arquivo .xcstrings. Abra o arquivo no Xcode para ver as traduções preenchidas para cada idioma configurado.

Depois de editar as strings de origem, um simples lingo push traduz apenas o delta — entradas cuja origem não mudou são ignoradas no servidor e rastreadas pelo lockfile:

lingo push

Notas para tradutores#

String Catalogs oferecem suporte a um campo de comentário por entrada, que a CLI inclui nas solicitações de tradução. Esses comentários dão contexto à engine de localização — ajudam a desambiguar termos, especificar o tom ou indicar onde a string aparece na interface.

No Xcode, selecione uma string no editor de String Catalog e adicione um comentário no painel do inspetor. O comentário é armazenado no JSON .xcstrings:

{
  "sourceLanguage": "en",
  "strings": {
    "Set": {
      "comment": "Refers to a collection of items, not the verb",
      "localizations": { }
    }
  }
}

A CLI envia esse comentário junto com a string, orientando o modelo para a interpretação correta. "Set", sem contexto, pode virar um verbo em muitos idiomas — o comentário elimina essa ambiguidade. Veja Translator Notes para conhecer mais padrões.

Plurais#

String Catalogs tratam formas plurais nativamente com regras de plural do CLDR. Quando você define uma variação plural no Xcode, o String Catalog armazena regras para cada categoria de plural (zero, one, two, few, many, other) exigida pelo idioma de destino.

A CLI preserva essa estrutura durante a tradução e gera as categorias de plural corretas para cada idioma de destino. O inglês usa duas categorias (one e other), mas o árabe precisa de seis, o polonês de quatro e o japonês de uma. A engine de localização lida com essas diferenças automaticamente.

Automatize com o GitHub App#

Instale o Lingo.dev GitHub App no seu repositório para Localização contínua — sem runner de CI, secret de chave de API ou lockfile para gerenciar. Depois de instalado e apontado para o seu .lingo/config.json (com seu engineId), ele reage automaticamente a pushes e pull requests: detecta strings de origem alteradas, traduz por meio do seu engine e faz commit do .xcstrings atualizado de volta na branch ou abre um pull request.

Verifique antes do deploy#

Use lingo check como gate de deploy para garantir que nenhuma string sem tradução chegue à produção. Ele informa traduções ausentes ou desatualizadas e encerra com um status diferente de zero quando ainda há trabalho pendente:

lingo check

Adicione isso como uma etapa separada de CI antes do build.

Próximos passos#