Localização de aplicações Android com strings.xml

A CLI da Lingo.dev traduz recursos de strings de Android (strings.xml) através de um motor de localização configurado. Com o formato android, a CLI reconhece nativamente os elementos <resources>, <string>, <string-array> e <plurals>, preservando a estrutura XML e gerando as categorias de plural corretas para cada idioma de destino.

Este guia acompanha todo o processo de localização de uma app Android: configurar a CLI, traduzir localmente e automatizar em CI para que as traduções sejam incluídas a cada push.

Como funciona a localização no Android#

O Android segue uma convenção de diretórios de recursos em que cada idioma tem o seu próprio diretório values-[locale]/. O sistema carrega o strings.xml correto em tempo de execução com base na definição de idioma do dispositivo.

app/src/main/res/
  values/              # Default (source) strings
    strings.xml
  values-es/           # Spanish
    strings.xml
  values-fr/           # French
    strings.xml
  values-ja/           # Japanese
    strings.xml

Um strings.xml típico contém três tipos de elementos:

<resources>
  <!-- Simple strings -->
  <string name="app_name">My App</string>
  <string name="welcome_message">Welcome back!</string>

  <!-- String arrays -->
  <string-array name="planets">
    <item>Mercury</item>
    <item>Venus</item>
    <item>Earth</item>
  </string-array>

  <!-- Plurals -->
  <plurals name="items_count">
    <item quantity="one">%d item</item>
    <item quantity="other">%d items</item>
  </plurals>
</resources>

A CLI analisa os três tipos de elementos, traduz o respetivo conteúdo através do motor de localização e grava ficheiros por idioma nos diretórios values-[locale]/ corretos.

Pré-requisitos#

node -v

npm install -g @lingo.dev/cli

lingo login

Configurar a CLI#

Execute lingo init na raiz do projeto para criar .lingo/config.json com os idiomas de origem e destino e os padrões de ficheiros e, em seguida, lingo link para associar a sua organização e o motor. O resultado será semelhante a este:

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    {
      "pattern": "app/src/main/res/values/strings.xml",
      "format": "android"
    }
  ]
}

O padrão aponta para o diretório de recursos predefinido — o values/ sem qualificador, exatamente onde o Android espera encontrar as strings de origem. Não inclui qualquer código de idioma, nem precisa de incluir.

{
  "files": [
    {
      "pattern": "app/src/main/res/values/strings.xml",
      "format": "android"
    },
    {
      "pattern": "app/src/main/res/values/arrays.xml",
      "format": "android"
    }
  ]
}

Faça commit de .lingo/config.json no repositório.

Diretórios de idioma e qualificadores#

No Android, o idioma predefinido fica num diretório values/ sem qualificador, por isso o caminho de origem não inclui qualquer código de idioma. O CLI reconhece este padrão: trata values/ sem qualificador como o idioma de origem e acrescenta o qualificador de destino para todos os restantes idiomas.

Vale a pena perceber aqui como funcionam os idiomas regionais e com escrita específica, porque um qualificador de recursos não é uma etiqueta BCP 47 em bruto. O Android aceita duas formas: o formato legado idioma-região (values-pt-rBR/) e um formato BCP 47 com o prefixo b+ (values-b+pt+BR/, API 24 e superior). Um diretório chamado values-pt-BR/ é simplesmente ignorado — as strings até podem existir, mas nunca serão carregadas.

Ao definir "format": "android", o CLI gera automaticamente a forma correta: o formato legado sempre que consegue representar o idioma e b+ para escritas, idiomas de três letras e regiões numéricas.

Traduzir localmente#

Execute a CLI. Na primeira execução — ou sempre que adicionar um novo idioma de destino — use --backfill-missing para traduzir todas as strings existentes:

lingo push --backfill-missing

A CLI lê o strings.xml de origem, identifica as entradas por traduzir com base no estado de execução, traduz o delta através do motor de localização e escreve os resultados nos diretórios values-[locale]/ de destino. Abra qualquer ficheiro de destino para ver as strings traduzidas.

Nas execuções seguintes, lingo push traduz apenas o que mudou:

lingo push

Para limitar uma execução a ficheiros específicos, passe um glob. Os padrões são comparados com os caminhos de origem, por isso a filtragem deve ser feita pelo ficheiro de origem, e não pelo destino:

lingo push "app/src/main/res/values/strings.xml"

Para ir buscar à sua árvore de trabalho traduções geradas noutro contexto (por exemplo, por CI), execute lingo pull.

Plurais#

O Android usa elementos <plurals> com strings de quantidade CLDR (zero, one, two, few, many, other) para tratar formas de plural. Idiomas diferentes exigem categorias de plural diferentes — o inglês precisa de duas (one e other), o russo precisa de quatro e o árabe precisa de seis.

A CLI preserva a estrutura <plurals> durante a tradução e gera as entradas de quantidade corretas para cada idioma de destino. Uma entrada de origem com duas categorias:

<plurals name="messages_count">
  <item quantity="one">%d new message</item>
  <item quantity="other">%d new messages</item>
</plurals>

Gera as categorias corretas para cada idioma de destino. O motor de localização sabe que regras de plural CLDR se aplicam a cada idioma e gera apenas as categorias de que esse idioma precisa.

Bloqueio de chaves#

Alguns valores de string devem manter-se idênticos em todos os idiomas — nomes de marcas, endpoints de API ou padrões de formato. Use o bloqueio de chaves para copiar estes valores sem tradução:

{
  "files": [
    {
      "pattern": "app/src/main/res/values/strings.xml",
      "format": "android",
      "lockedKeys": ["app_name", "api_base_url"]
    }
  ]
}

As chaves bloqueadas são copiadas da origem para todos os ficheiros de destino sem entrarem no pipeline de tradução.

Automatizar em CI#

A forma recomendada de manter as traduções atualizadas é a GitHub App da Lingo.dev. Corre do lado do servidor, lê os ficheiros .lingo/config.json e engineId já committed e abre automaticamente atualizações de tradução — sem runner, sem segredos armazenados e sem gestão de lockfiles do seu lado. Instale-a e ligue-a ao seu repositório para traduzir a cada push.

Se preferir executar a CLI no seu próprio pipeline, adicione um workflow que instale a CLI e execute lingo push:

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @lingo.dev/cli
      - run: lingo push --backfill-missing
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}

Guarde a sua chave de API como LINGO_API_KEY em Settings > Secrets and variables > Actions no seu repositório GitHub e, em seguida, faça commit dos ficheiros de destino atualizados (ou abra um pull request) como passo seguinte.

Verificar antes de implementar#

Use lingo check como gate de deployment para garantir que nenhuma string por traduzir chega à produção. O comando termina com um estado diferente de zero se alguma entrada precisar de tradução:

lingo check

Adicione isto como um passo de CI separado antes da compilação:

- name: Verify translations
  run: lingo check
  env:
    LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}

Próximos passos#