Localização de apps iOS com Xcode String Catalogs

A CLI da Lingo.dev traduz Xcode String Catalogs (.xcstrings) através de um motor de localização configurado. Os String Catalogs são o formato moderno de localização da Apple, introduzido no Xcode 15, que guarda todos os idiomas num único ficheiro JSON. A CLI altera este ficheiro no local — sem necessidade de diretórios por idioma.

Este guia acompanha todo o processo de localização de uma app iOS: configurar a CLI, traduzir localmente e automatizar com a GitHub App para que as traduções sejam entregues a cada push.

Como funcionam os String Catalogs#

Antes do Xcode 15, a localização no iOS exigia gerir ficheiros .strings e .stringsdict separados em vários diretórios [locale].lproj/. Os String Catalogs substituem esta abordagem por um único ficheiro Localizable.xcstrings que o Xcode mantém automaticamente.

Quando marca uma string como localizável em SwiftUI ou UIKit, o Xcode deteta-a durante a compilação e adiciona uma entrada ao String Catalog. Cada entrada inclui a string de origem, as respetivas traduções para cada idioma configurado e um campo de comentário opcional que dá contexto aos tradutores.

A CLI deteta o formato .xcstrings pela extensão do ficheiro, analisa esta estrutura JSON, traduz cada entrada através do motor de localização e escreve as traduções de volta no mesmo ficheiro, preservando comentários, regras de plural e metadados.

Pré-requisitos#

node -v

Instalar e configurar a CLI#

Instale a CLI, autentique-se e configure o projeto. Consulte o Quickstart para ver o guia completo.

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

Execute lingo init na raiz do projeto e responda às instruções (idioma de origem, idiomas de destino e o padrão de ficheiro que aponta para o seu String Catalog) e, em seguida, execute lingo link para associar o projeto à sua organização e motor. Em conjunto, estes comandos escrevem 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 — é a fonte de verdade do que será traduzido. O formato .xcstrings é detetado pela extensão do ficheiro. Como os String Catalogs armazenam todos os idiomas num único ficheiro, não é necessário qualquer marcador de posição de idioma no padrão: a CLI lê as entradas no idioma de origem e escreve todos os idiomas de destino de volta no mesmo ficheiro. Consulte a referência de configuração para ver o esquema completo.

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

Traduzir localmente#

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

lingo push --backfill-missing

A CLI lê o seu String Catalog, traduz todas as entradas em falta através do seu motor de localização, aguarda que a execução termine e escreve os resultados de volta no ficheiro .xcstrings. Abra o ficheiro 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 — as entradas cuja origem não mudou são ignoradas no servidor e controladas através do lockfile:

lingo push

Notas para tradutores#

Os String Catalogs suportam um campo de comentário por entrada, que a CLI inclui nos pedidos de tradução. Estes comentários dão contexto ao motor de localização — desambiguam termos, especificam o tom ou descrevem onde uma string aparece na UI.

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

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

A CLI envia este comentário juntamente com a string, orientando o modelo para a interpretação correta. "Set", sem contexto, pode tornar-se um verbo em muitas línguas — o comentário elimina essa ambiguidade. Consulte Translator Notes para ver mais padrões.

Plurais#

Os String Catalogs tratam formas de plural de forma nativa através das regras de plural CLDR. Quando define uma variação de 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 esta 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 polaco de quatro e o japonês de uma. O motor de localização trata automaticamente estas diferenças.

Automatizar com a GitHub App#

Instale a Lingo.dev GitHub App no seu repositório para Localização Contínua — sem runner de CI, segredo de API key ou lockfile para gerir. Depois de instalada e apontada para o seu .lingo/config.json (com o respetivo engineId), reage automaticamente a pushes e pull requests: deteta strings de origem alteradas, traduz-as através do seu motor e faz commit do .xcstrings atualizado de volta para a branch ou abre um pull request.

Verificar antes de fazer deploy#

Use lingo check como gate de deployment para garantir que nenhuma string por traduzir chega à produção. O comando assinala traduções em falta ou desatualizadas e termina com um estado diferente de zero quando ainda há trabalho por fazer:

lingo check

Adicione-o como uma etapa de CI separada antes da build.

Próximos passos#