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

A CLI da Lingo.dev traduz recursos de string do Android (strings.xml) através de um motor de localização configurado. O tipo de bucket android da CLI compreende 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 mostra, de ponta a ponta, como localizar uma aplicação Android: configurar a CLI, traduzir localmente e automatizar com GitHub Actions para que as traduções sejam incluídas em 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

Configurar a CLI#

Crie um ficheiro i18n.json na raiz do projeto. O bucket android indica à CLI que deve analisar os recursos XML do Android e criar ficheiros 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 marcador de posição [locale] é resolvido para cada código de idioma configurado em tempo de execução. A CLI substitui o idioma de origem no padrão — por isso, com source: "en", procura values-en/strings.xml. Os idiomas de destino geram values-es/strings.xml, values-fr/strings.xml e assim sucessivamente.

Fazer a ponte com o diretório do idioma predefinido#

O Android armazena as strings predefinidas em values/ (sem sufixo de idioma), mas a CLI resolve [locale] literalmente e procura values-en/strings.xml. Crie uma ligação simbólica para fazer a ponte entre as duas convenções:

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

Isto torna as strings de origem visíveis tanto em values/strings.xml (onde o Android as espera) como em values-en/strings.xml (onde a CLI as procura). Faça commit da ligação simbólica no repositório — o git suporta ligações simbólicas 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"
      ]
    }
  }
}

Traduzir localmente#

Defina a 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 por traduzir com o lockfile, traduz o delta através do motor de localização e grava os resultados nos diretórios values-[locale]/ de destino. Abra qualquer ficheiro de destino para ver as strings traduzidas.

Para direcionar 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 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:

{
  "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 ficheiros de destino sem entrarem no pipeline de tradução.

Automatizar com GitHub Actions#

Adicione um ficheiro 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 }}

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

Verificar antes de implementar#

Use a flag --frozen como controlo de implementação para garantir que nenhuma string por traduzir chega à produção. A CLI termina com um estado diferente de zero se alguma entrada precisar de tradução:

npx lingo.dev@latest run --frozen

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

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

Próximos passos#