Table des matières
Localisation API-First : Intégrer la Traduction dans votre Workflow de Développement
Points Clés
- La localisation API-first remplace l'échange manuel de fichiers par une synchronisation automatisée entre votre base de code et le système de gestion des traductions
- Les outils CLI et les intégrations CI/CD permettent des workflows push/pull qui maintiennent les traductions synchronisées à chaque déploiement
- Les notifications basées sur les webhooks déclenchent des builds lorsque les traductions sont mises à jour, permettant une localisation continue
- Les approches API-first réduisent le délai de mise sur le marché pour les nouvelles langues de plusieurs semaines à quelques heures
Qu'est-ce que la Localisation API-First ?
La localisation API-first est une approche dans laquelle le système de gestion des traductions (TMS) fournit un accès programmatique à tous les workflows de traduction via des REST APIs, des outils CLI et des webhooks. Au lieu d'exporter/importer manuellement des fichiers de traduction, les développeurs intègrent la synchronisation des traductions directement dans leurs pipelines de build et de déploiement.
Le Workflow Traditionnel vs. API-First
Traditionnel (Basé sur les Fichiers)
- Le développeur exporte les chaînes sources vers un fichier (JSON, XLIFF, etc.)
- Le fichier est téléchargé dans le TMS ou envoyé aux traducteurs par e-mail
- Les fichiers traduits sont retournés après des jours/semaines
- Le développeur télécharge et place les fichiers dans les bons répertoires
- Le développeur fait un commit et déploie
Problèmes : Étapes manuelles, dérive de version, conflits de merge, cycles lents.
API-First
- Le développeur pousse les nouvelles chaînes via CLI :
better-i18n push - Le TMS notifie les traducteurs du nouveau contenu
- Les traducteurs travaillent dans l'éditeur TMS avec le contexte complet
- Le webhook déclenche le CI/CD lorsque les traductions sont terminées
- Le build récupère les dernières traductions :
better-i18n pull - Le déploiement inclut automatiquement les traductions mises à jour
Avantages : Pas de gestion manuelle de fichiers, synchronisation continue, cycles plus rapides.
Composants Principaux de la Localisation API-First
REST API
L'API du TMS fournit des endpoints pour :
POST /api/keys — Créer de nouvelles clés de traduction GET /api/translations — Récupérer les traductions pour un locale PUT /api/translations — Mettre à jour les traductions GET /api/projects — Lister les projets et leur statut POST /api/upload — Télécharger des fichiers sources GET /api/download — Télécharger les fichiers traduits
Outil CLI
Un outil en ligne de commande qui encapsule l'API pour faciliter le travail des développeurs :
# Pousser les nouvelles chaînes sources vers le TMS better-i18n push # Récupérer les dernières traductions better-i18n pull --locale=de,fr,ja # Vérifier le statut des traductions better-i18n status # Scanner la base de code pour les chaînes non traduites better-i18n scan
Webhooks
Notifications événementielles lorsque les traductions changent :
{
"event": "translations.completed",
"project": "my-app",
"locale": "de",
"completed_keys": 142,
"total_keys": 142
}
Utilisez les webhooks pour déclencher des pipelines CI/CD, des notifications Slack ou des déploiements automatisés.
Intégration CI/CD
Intégrez la synchronisation des traductions dans votre pipeline de build :
# Exemple GitHub Actions
- name: Pull translations
run: better-i18n pull --all
env:
BETTER_I18N_TOKEN: ${{ secrets.BETTER_I18N_TOKEN }}
- name: Build
run: npm run build
Avantages de la Localisation API-First
| Avantage | Impact |
|---|---|
| Synchronisation automatisée | Pas de gestion manuelle de fichiers |
| Contrôle de version | Les traductions sont suivies avec le code |
| Livraison continue | Les nouvelles traductions sont publiées à chaque déploiement |
| Expérience développeur | Workflow CLI/API familier |
| Mise sur le marché plus rapide | Nouvelles langues en heures, pas en semaines |
| Moins d'erreurs | Pas de problèmes de format de fichier ni de fichiers mal placés |
Modèles d'Implémentation
Modèle 1 : Pull au Moment du Build
Récupérez les traductions lors de l'étape de build. Les traductions sont intégrées dans l'application au moment du build.
Idéal pour : Les sites statiques, les pages pré-rendues, les applications mobiles.
Modèle 2 : Fetch à l'Exécution
Récupérez les traductions depuis l'API à l'exécution. Permet des mises à jour instantanées sans redéploiement.
Idéal pour : Les SPAs, les applications web dynamiques, le contenu en temps réel.
Modèle 3 : Hybride
Récupérez les traductions au moment du build pour le chargement initial, et obtenez les mises à jour à l'exécution pour les correctifs urgents.
Idéal pour : Les applications en production qui nécessitent à la fois performance et flexibilité.
FAQ
Dois-je changer mon format de fichier pour utiliser la localisation API-first ? Non. La plupart des plateformes TMS API-first prennent en charge les formats standards (JSON, XLIFF, YAML, .strings, .xml) et gèrent automatiquement la conversion de format.
Comment gérer les clés de traduction qui sont renommées ou supprimées ?
La commande scan de la CLI détecte les clés inutilisées. Les endpoints de l'API permettent des opérations par lot sur les clés. La plupart des plateformes TMS suivent le cycle de vie des clés et signalent les traductions orphelines.
Que se passe-t-il si l'API est indisponible lors d'un build ? Utilisez des traductions en cache comme solution de repli. Stockez le dernier pull réussi dans le contrôle de version afin que les builds aient toujours une base, même si l'API est inaccessible.
Comment gérer les traductions pour plusieurs environnements ? Utilisez un namespacing au niveau du projet ou de la branche. Certaines plateformes TMS prennent en charge des remplacements spécifiques à l'environnement (staging, production) pour le même projet.
La localisation API-first convient-elle aux petits projets ? Oui. Le workflow CLI push/pull est plus simple que la gestion manuelle de fichiers même pour des projets avec quelques centaines de chaînes. La mise en place de l'intégration API est minimale par rapport au temps économisé.
