Localização de apps Android com strings.xml

A CLI da Lingo.dev traduz recursos de string do Android (strings.xml) por meio de um engine de localização configurado. O tipo de bucket android da CLI entende nativamente os elementos <resources>, <string>, <string-array> e <plurals>, preservando a estrutura do XML e gerando as categorias de plural corretas para cada idioma de destino.

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

Como funciona a localização no Android#

O Android usa uma convenção de diretórios de recursos em que cada idioma tem seu próprio diretório values-[locale]/. Em tempo de execução, o sistema carrega o strings.xml correto com base na configuraçã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 conteúdo por meio do engine de localização e grava arquivos por idioma nos diretórios values-[locale]/ corretos.

Pré-requisitos#

node -v

Configure a CLI#

Crie um arquivo i18n.json na raiz do projeto. O bucket android instrui a CLI a analisar os recursos XML do Android e criar arquivos separados por idioma:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"]
    }
  }
}

O placeholder [locale] é resolvido para cada código de idioma configurado em tempo de execução. A CLI substitui o idioma de origem no padrão — então, com source: "en", ela procura por values-en/strings.xml. Os idiomas de destino geram values-es/strings.xml, values-fr/strings.xml e assim por diante.

Conecte o diretório do idioma padrão#

O Android armazena as strings padrão em values/ (sem sufixo de idioma), mas a CLI resolve [locale] literalmente e procura por values-en/strings.xml. Crie um symlink para conectar as duas convenções:

cd app/src/main/res
ln -s values values-en

Isso deixa as strings de origem visíveis tanto em values/strings.xml (onde o Android espera encontrá-las) quanto em values-en/strings.xml (onde a CLI procura). Faça commit do symlink no repositório — o git rastreia symlinks nativamente no macOS e no Linux.

{
  "buckets": {
    "android": {
      "include": [
        "app/src/main/res/values-[locale]/strings.xml",
        "app/src/main/res/values-[locale]/arrays.xml"
      ]
    }
  }
}

Traduza localmente#

Defina sua chave de API e execute a CLI:

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

A CLI lê o strings.xml de origem, identifica entradas ainda não traduzidas usando o lockfile, traduz o delta por meio do engine de localização e grava os resultados nos diretórios de destino values-[locale]/. Abra qualquer arquivo de destino para ver as strings traduzidas.

Para segmentar um idioma específico durante o desenvolvimento:

npx lingo.dev@latest run --target-locale es

Plurais#

O Android usa elementos <plurals> com strings de quantidade do CLDR (zero, one, two, few, many, other) para lidar com 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 de <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 engine de localização sabe quais regras de plural do CLDR se aplicam a cada idioma e gera apenas as categorias exigidas por aquela língua.

Bloqueio de chaves#

Alguns valores de string precisam permanecer idênticos em todos os idiomas — nomes de marca, endpoints de API ou padrões de formatação. Use o bloqueio de chaves para copiar esses valores sem traduzi-los:

{
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"],
      "lockedKeys": ["app_name", "api_base_url"]
    }
  }
}

As chaves bloqueadas são copiadas da origem para todos os arquivos de destino sem passar pelo pipeline de tradução.

Automatize com GitHub Actions#

Adicione um arquivo de workflow em .github/workflows/translate.yml para traduzir a cada push:

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Armazene sua chave de API como LINGODOTDEV_API_KEY em Settings > Secrets and variables > Actions no repositório do GitHub.

Verifique antes de implantar#

Use a flag --frozen como gate de deploy para garantir que nenhuma string sem tradução chegue à produção. A CLI retorna um status diferente de zero se alguma entrada precisar de tradução:

npx lingo.dev@latest run --frozen

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

- name: Verify translations
  run: npx lingo.dev@latest run --frozen

Próximos passos#