Localisation d’app iOS avec les String Catalogs Xcode

Le CLI Lingo.dev traduit les String Catalogs Xcode (.xcstrings) via un moteur de localisation configuré. Les String Catalogs sont le format de localisation moderne d’Apple, introduit avec Xcode 15, qui regroupe toutes les langues dans un seul fichier JSON. Le CLI modifie ce fichier directement, sans nécessiter de répertoires distincts par langue.

Ce guide vous accompagne de bout en bout dans la localisation d’une app iOS : configuration du CLI, traduction en local et automatisation avec GitHub Actions pour livrer les traductions à chaque push.

Comment fonctionnent les String Catalogs#

Avant Xcode 15, la localisation iOS impliquait de gérer des fichiers .strings et .stringsdict séparés dans des répertoires [locale].lproj/. Les String Catalogs remplacent cette approche par un unique fichier Localizable.xcstrings que Xcode maintient automatiquement.

Lorsque vous marquez une chaîne comme localisable dans SwiftUI ou UIKit, Xcode la détecte au moment du build et ajoute une entrée au String Catalog. Chaque entrée suit la chaîne source, ses traductions pour chaque langue configurée et un champ de commentaire facultatif qui apporte du contexte aux traducteurs.

Le type de bucket xcode-xcstrings du CLI analyse cette structure JSON, traduit chaque entrée via le moteur de localisation, puis réécrit les traductions dans le même fichier, tout en préservant les commentaires, les règles de pluriel et les métadonnées.

Prérequis#

node -v

Configurer le CLI#

Créez un fichier i18n.json à la racine de votre projet. Le bucket xcode-xcstrings indique au CLI d’analyser le format String Catalog et de modifier le fichier directement :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "xcode-xcstrings": {
      "include": ["MyApp/Localizable.xcstrings"]
    }
  }
}

Comme les String Catalogs regroupent toutes les langues dans un seul fichier, aucun placeholder [locale] n’est nécessaire dans le motif include. Le CLI lit les entrées de la langue source, les traduit, puis réécrit toutes les langues cibles dans le même fichier .xcstrings.

{
  "buckets": {
    "xcode-xcstrings": {
      "include": [
        "MyApp/Localizable.xcstrings",
        "MyAppWidgets/Localizable.xcstrings"
      ]
    }
  }
}

Traduire en local#

Définissez votre clé API et lancez le CLI :

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

Le CLI lit votre String Catalog, repère les entrées non traduites à l’aide du lockfile, traduit le delta via votre moteur de localisation, puis réécrit le résultat dans le fichier .xcstrings. Ouvrez le fichier dans Xcode pour voir les traductions renseignées pour chaque langue configurée.

Pour cibler une langue spécifique pendant le développement :

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

Notes pour les traducteurs#

Les String Catalogs prennent en charge un champ de commentaire par entrée, que le CLI inclut dans les requêtes de traduction. Ces commentaires fournissent du contexte au moteur de localisation, en levant les ambiguïtés, en précisant le ton ou en indiquant où une chaîne apparaît dans l’interface.

Dans Xcode, sélectionnez une chaîne dans l’éditeur de String Catalog et ajoutez un commentaire dans le panneau de l’inspecteur. Le commentaire est stocké dans le JSON .xcstrings :

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

Le CLI envoie ce commentaire avec la chaîne afin d’orienter le modèle vers la bonne interprétation. Sans contexte, « Set » pourrait être compris comme un verbe dans de nombreuses langues ; le commentaire lève cette ambiguïté. Voir Translator Notes pour découvrir d’autres cas d’usage.

Pluriels#

Les String Catalogs gèrent nativement les formes plurielles à l’aide des règles de pluriel CLDR. Lorsque vous définissez une variante plurielle dans Xcode, le String Catalog enregistre les règles pour chaque catégorie de pluriel (zero, one, two, few, many, other) requise par la langue cible.

Le CLI préserve cette structure pendant la traduction et génère les bonnes catégories de pluriel pour chaque langue cible. L’anglais en utilise deux (one et other), mais l’arabe en exige six, le polonais quatre et le japonais une seule. Le moteur de localisation gère automatiquement ces différences.

Automatiser avec GitHub Actions#

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

Stockez 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 statut non nul si certaines entrées doivent encore être traduites :

npx lingo.dev@latest run --frozen

Ajoutez cette étape CI séparément avant votre build :

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

Étapes suivantes#