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 A à Z pour localiser une app iOS : configuration de la CLI, traduction en local et automatisation avec la GitHub App 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.

La CLI détecte le format .xcstrings à partir de l’extension du fichier, 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

Installer et configurer la CLI#

Installez la CLI, authentifiez-vous, puis configurez le projet. Consultez le Quickstart pour le guide complet.

npm install -g @lingo.dev/cli
lingo login

Exécutez lingo init à la racine de votre projet et répondez aux invites (langue source, langues cibles et motif de fichier pointant vers votre catalogue de chaînes), puis lingo link pour lier le projet à votre organisation et à votre moteur. Ces commandes génèrent ensemble un .lingo/config.json :

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "MyApp/Localizable.xcstrings" }]
}

Validez .lingo/config.json : c’est la source de vérité de ce qui doit être traduit. Le format .xcstrings est détecté à partir de l’extension du fichier. Comme les catalogues de chaînes regroupent toutes les langues dans un seul fichier, aucun placeholder de langue n’est nécessaire dans le motif : la CLI lit les entrées dans la langue source et réécrit toutes les langues cibles dans ce même fichier. Consultez la référence de configuration pour le schéma complet.

{
  "files": [
    { "pattern": "MyApp/Localizable.xcstrings" },
    { "pattern": "MyAppWidgets/Localizable.xcstrings" }
  ]
}

Traduire en local#

Depuis la racine de votre projet, lancez la première traduction :

lingo push --backfill-missing

La CLI lit votre catalogue de chaînes, traduit chaque entrée manquante via votre moteur de localisation, attend la fin de l’exécution, puis écrit les résultats dans le fichier .xcstrings. Ouvrez-le dans Xcode pour voir les traductions renseignées pour chaque langue configurée.

Après modification des chaînes source, un simple lingo push ne traduit que le delta : les entrées dont la source n’a pas changé sont ignorées côté serveur et suivies via le fichier de verrouillage :

lingo push

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 la GitHub App#

Installez la GitHub App Lingo.dev sur votre dépôt pour une Localisation continue, sans runner CI, secret de clé API ni fichier de verrouillage à gérer. Une fois installée et reliée à votre .lingo/config.json (avec son engineId), elle réagit automatiquement aux pushs et aux pull requests : elle détecte les chaînes source modifiées, les traduit via votre moteur, puis commit le .xcstrings mis à jour sur la branche ou ouvre une pull request.

Vérifier avant le déploiement#

Utilisez lingo check comme garde-fou de déploiement pour vous assurer qu’aucune chaîne non traduite n’arrive en production. Il signale les traductions manquantes ou obsolètes et se termine avec un statut non nul lorsqu’il reste du travail :

lingo check

Ajoutez-le comme étape CI distincte avant votre build.

Étapes suivantes#