Valider les imports XLIFF de Xcode sur un Mac dans le cloud

À l’approche du gel d’une version, le prestataire de traduction livre généralement plusieurs fichiers .xcloc ou .xliff. Les importer directement par un double-clic dans l’espace de travail quotidien d’un développeur peut sembler rapide, mais cette méthode risque d’injecter dans le projet des clés de traduction obsolètes, une langue cible incorrecte ou des espaces réservés endommagés. Une approche plus sûre consiste à créer un répertoire de validation éphémère sur un Mac dans le cloud : exportez d’abord une référence depuis le commit actuel, effectuez les contrôles préalables sur les fichiers reçus, puis importez-les, examinez les différences et lancez la compilation.

Figer l’environnement de validation

Le nœud de validation doit partir d’un commit propre. Ne réutilisez pas un espace de travail dans lequel des fichiers de localisation ont déjà été importés et n’effectuez aucun test dans un répertoire contenant des modifications non validées. Pour chaque livraison, vous pouvez créer une branche temporaire ou un worktree distinct :

git fetch origin
git worktree add ../localization-review origin/main
cd ../localization-review
git switch -c review/localization-batch
xcodebuild -version
git status --short

Consignez dans les journaux la sortie de xcodebuild -version, le SHA du commit, le Scheme cible et le lot livré. Si l’équipe utilise plusieurs versions de Xcode, définissez également DEVELOPER_DIR de manière explicite afin d’éviter que le terminal interactif et les tâches automatisées n’emploient des chaînes d’outils différentes.

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
xcode-select -p
git rev-parse HEAD

Le critère de référence d’une validation de localisation n’est pas que « le fichier s’ouvre », mais que le même commit, la même chaîne d’outils Xcode et le même ensemble de paramètres d’exportation produisent des résultats explicables.

Sur un Mac cloud de GPUMini, commencez par vérifier dans la console les configurations actuellement disponibles, puis choisissez le nœud destiné à la validation. Cette tâche exige rarement une forte concurrence, mais si l’importation doit être suivie de la compilation complète d’un projet volumineux, prévoyez tout de même une marge suffisante de mémoire et d’espace disque.

Exporter une référence depuis le projet actuel

Pour un fichier .xcodeproj, utilisez les paramètres du projet. Si le projet repose sur un Workspace, remplacez-les par -workspace et indiquez un Scheme partagé. L’exemple suivant exporte le chinois simplifié, le japonais et le français. Répétez -exportLanguage pour ajouter d’autres langues :

mkdir -p Artifacts/Baseline
xcodebuild \
  -project ExampleApp.xcodeproj \
  -scheme ExampleApp \
  -exportLocalizations \
  -localizationPath Artifacts/Baseline \
  -exportLanguage zh-Hans \
  -exportLanguage ja \
  -exportLanguage fr

Une fois l’exportation terminée, enregistrez d’abord l’inventaire des fichiers au lieu d’écraser immédiatement les traductions reçues :

find Artifacts/Baseline -type f -print0 \
  | sort -z \
  | xargs -0 shasum -a 256 > Artifacts/baseline.sha256

Cette référence répond à trois questions : quelles unités sont traduisibles dans le projet actuel, quel est le contenu de la langue source et quelles langues cibles Xcode reconnaît. Si les fichiers livrés contiennent des clés absentes de la référence, la traduction a probablement été réalisée à partir d’un ancien commit. Si la référence comporte au contraire de nombreuses nouvelles unités non traduites, des fonctionnalités récentes ont peut-être été omises du périmètre livré.

Contrôler la structure et les espaces réservés avant l’importation

Un fichier XLIFF est avant tout un document XML. Commencez par vérifier son format avec les outils système, puis extrayez les attributs de langue et le nombre d’unités de traduction. N’utilisez pas d’expressions régulières pour réécrire du XML : les contrôles préalables peuvent lire les fichiers, mais les corrections doivent être effectuées dans l’outil de localisation ou au moyen d’un script dûment vérifié.

find Incoming -name "*.xliff" -print0 |
while IFS= read -r -d '' file; do
  echo "Checking $file"
  xmllint --noout "$file"
  xmllint --xpath \
    'string(/*[local-name()="xliff"]/*[local-name()="file"][1]/@target-language)' \
    "$file"
  echo
done

Les espaces réservés constituent le principal motif de blocage. %@, %d, les paramètres positionnels et les variables générées par String Catalog doivent conserver une correspondance sémantique entre la source et la traduction. Il ne suffit pas de compter les signes de pourcentage, car %%, les largeurs de format et les paramètres positionnels ont des significations différentes. Il est recommandé d’utiliser un analyseur XML pour lire séparément les éléments source et target de chaque trans-unit, de normaliser les espaces réservés, puis de comparer les multi-ensembles obtenus.

Pour les chaînes de format visibles par l’utilisateur, vérifiez également par échantillonnage les sauts de ligne, les caractères d’échappement et les branches de pluriel. L’ordre des espaces réservés peut varier selon la langue, mais lorsque des paramètres positionnels sont utilisés, leurs indices doivent rester valides.

Importer dans un répertoire isolé et examiner les différences

Une fois les contrôles préalables réussis, importez les paquets .xcloc un par un. Enregistrez l’état immédiatement après chaque importation afin de déterminer facilement quel fichier livré a introduit une anomalie :

mkdir -p Artifacts/Logs
for package in Incoming/*.xcloc; do
  name="$(basename "$package" .xcloc)"
  xcodebuild \
    -project ExampleApp.xcodeproj \
    -importLocalizations \
    -localizationPath "$package" \
    2>&1 | tee "Artifacts/Logs/import-${name}.log"
  test "${PIPESTATUS[0]}" -eq 0 || exit 1
  git status --short
done

Une importation réussie ne signifie pas que la validation est terminée. Commencez par utiliser git diff --stat pour évaluer l’étendue des modifications, puis examinez les différences fichier par fichier. Les changements normaux doivent se concentrer dans les String Catalogs, les ressources de chaînes ou les répertoires des langues concernées. Si des Schemes, des réglages de compilation, des paramètres de signature ou des fichiers de projet sans rapport ont été modifiés, interrompez la procédure et identifiez-en la cause.

git diff --stat
git diff --check
git diff -- '*.xcstrings' '*.strings' '*.stringsdict' 'project.pbxproj'

git diff --check permet de détecter certains espaces de fin de ligne et certaines traces de conflits, mais ne peut pas évaluer le sens d’une traduction. Il est recommandé de produire un récapitulatif des unités de traduction ajoutées, supprimées et modifiées, puis de le conserver avec les journaux d’importation parmi les artefacts du pipeline.

Boucler la validation par une compilation et une réexportation

Enfin, effectuez une compilation propre du Scheme cible. Si le projet contient plusieurs cibles d’application ou des extensions, couvrez le parcours réellement utilisé pour la publication au lieu de compiler uniquement la cible de bibliothèque minimale.

set -o pipefail
xcodebuild \
  -project ExampleApp.xcodeproj \
  -scheme ExampleApp \
  -configuration Release \
  -destination 'generic/platform=iOS Simulator' \
  clean build |
  tee Artifacts/Logs/localization-build.log

Une fois la compilation réussie, réexportez les fichiers XLIFF depuis le projet après importation et comparez-les à la référence. Cette réexportation permet de repérer des traductions qui n’ont pas réellement été intégrées au projet, un mappage incorrect des codes de langue ou des unités toujours non traduites après l’importation. Lors de la comparaison, ignorez les simples différences de tri et les métadonnées générées par les outils ; concentrez-vous sur le texte source, le texte cible, l’état et les remarques de chaque unité de traduction.

Un pipeline de validation maintenable doit conserver explicitement quatre catégories de preuves : les informations sur la chaîne d’outils et le commit, le rapport des contrôles préalables, le récapitulatif des différences après importation et les journaux de compilation. En cas d’échec, ne nettoyez pas automatiquement le répertoire de travail : conservez d’abord l’état permettant le diagnostic. En cas de réussite, supprimez le worktree temporaire afin que le lot suivant n’hérite pas de l’ancien état.

Les critères de validation finaux peuvent se résumer ainsi : le XML est analysable, la langue cible est correcte, les ensembles d’espaces réservés correspondent, aucune unité de traduction inconnue n’est présente, l’étendue des différences est conforme aux attentes et la compilation du Scheme cible réussit. Le Mac dans le cloud devient ainsi un nœud reproductible de validation des localisations, et non un environnement d’importation supplémentaire dont la maintenance dépend de la mémoire humaine.

Questions fréquentes