Localisation d'une application Android avec strings.xml

Le CLI de Lingo.dev traduit les ressources string Android (strings.xml) à l’aide d’un moteur de localisation configuré. Le type de bucket android du CLI prend en charge nativement les éléments <resources>, <string>, <string-array> et <plurals>, tout en préservant la structure XML et en générant les bonnes catégories de pluriel pour chaque langue cible.

Ce guide vous montre comment localiser une application Android de bout en bout : configurer le CLI, traduire en local et automatiser le tout avec GitHub Actions pour livrer les traductions à chaque push.

Comment fonctionne la localisation Android#

Android s’appuie sur une convention de répertoires de ressources où chaque langue dispose de son propre répertoire values-[locale]/. Le système charge le bon fichier strings.xml à l’exécution, en fonction de la langue définie sur l’appareil.

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

Un fichier strings.xml standard contient trois types d’éléments :

<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>

Le CLI analyse ces trois types d’éléments, traduit leur contenu via le moteur de localisation, puis écrit un fichier par langue dans les bons répertoires values-[locale]/.

Prérequis#

node -v

Configurer le CLI#

Créez un fichier i18n.json à la racine du projet. Le bucket android indique au CLI d’analyser les ressources XML Android et de créer des fichiers distincts pour chaque langue :

{
  "$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"]
    }
  }
}

L’espace réservé [locale] est résolu à l’exécution avec le code de chaque langue configurée. Le CLI remplace votre langue source dans le modèle : avec source: "en", il recherche donc values-en/strings.xml. Les langues cibles génèrent values-es/strings.xml, values-fr/strings.xml, etc.

Faire le pont avec le répertoire de langue par défaut#

Android stocke les chaînes par défaut dans values/ (sans suffixe de langue), mais le CLI résout [locale] de façon littérale et recherche values-en/strings.xml. Créez un lien symbolique pour faire le lien entre ces deux conventions :

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

Les chaînes source sont ainsi visibles à la fois dans values/strings.xml (où Android les attend) et dans values-en/strings.xml (où le CLI les cherche). Versionnez le lien symbolique dans votre dépôt : git gère nativement les symlinks sur macOS et Linux.

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

Traduire en local#

Définissez votre clé API, puis lancez le CLI :

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

Le CLI lit votre fichier source strings.xml, repère les entrées non traduites à l’aide du lockfile, traduit uniquement le delta via votre moteur de localisation, puis écrit les résultats dans les répertoires cibles values-[locale]/. Ouvrez n’importe quel fichier cible pour voir les chaînes traduites.

Pour cibler une langue en particulier pendant le développement :

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

Pluriels#

Android utilise des éléments <plurals> avec des chaînes de quantité CLDR (zero, one, two, few, many, other) pour gérer les formes plurielles. Chaque langue a ses propres catégories de pluriel : l’anglais en utilise deux (one et other), le russe en utilise quatre et l’arabe six.

Le CLI préserve la structure <plurals> pendant la traduction et génère les entrées de quantité appropriées pour chaque langue cible. Une entrée source avec deux catégories :

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

Le CLI génère les bonnes catégories pour chaque langue cible. Le moteur de localisation sait quelles règles de pluriel CLDR s’appliquent à chaque langue et ne génère que les catégories requises.

Verrouillage des clés#

Certaines chaînes doivent rester identiques dans toutes les langues : noms de marque, endpoints d’API ou formats. Utilisez le verrouillage des clés pour recopier ces valeurs sans les traduire :

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

Les clés verrouillées sont copiées du fichier source vers tous les fichiers cibles, sans passer par le pipeline de traduction.

Automatiser avec GitHub Actions#

Ajoutez un fichier de workflow à l’emplacement .github/workflows/translate.yml pour lancer la traduction à chaque 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 }}

Enregistrez votre clé API sous LINGODOTDEV_API_KEY dans Settings > Secrets and variables > Actions de votre dépôt GitHub.

Vérifier avant le déploiement#

Utilisez l’option --frozen comme garde-fou avant déploiement pour vous assurer qu’aucune chaîne non traduite n’arrive en production. Le CLI renvoie un code de sortie non nul si certaines entrées doivent encore être traduites :

npx lingo.dev@latest run --frozen

Ajoutez cette vérification comme étape CI distincte avant votre build :

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

Étapes suivantes#