Migrer vers la CLI actuelle
Remplacez les anciens buckets et les empreintes du contenu source tout en conservant les traductions acceptées et une application fonctionnelle.
La @lingo.dev/cli actuelle repose sur des opérations push/pull côté serveur et sur un état de projet .lingo. L’ancien paquet lingo.dev utilise un traitement local des buckets, i18n.json et i18n.lock. Migrer, c’est préserver le comportement nécessaire au projet, et pas seulement changer le nom d’une commande.
Conserver un point de départ fonctionnel #
Notez la version installée et conservez les sources, les cibles acceptées, la configuration et l’ancien Lockfile dans le système de gestion de versions. Vérifiez que l’application charge bien ces cibles. Conservez le routeur, le fournisseur, le sélecteur de langue et le chargeur de catalogues de votre configuration de localisation existante jusqu’à ce qu’une solution de remplacement au périmètre limité soit opérationnelle.
Notez les versions du framework et de l’environnement d’exécution, ainsi que les langues source, cibles et par défaut requises. Testez un ensemble représentatif de routes préfixées par la langue, la détection initiale, le mécanisme de repli et le changement de langue. Distinguez ces vérifications de l’application de la migration du processus de traduction des fichiers.
Redéfinir la sélection des fichiers #
Créez .lingo/config.json en indiquant les langues source et cibles et en définissant explicitement les entrées de fichiers, puis associez votre organisation autorisée et votre moteur de localisation. Un simple renommage des anciens buckets et des empreintes ne suffit pas à les adapter à ce schéma.
La configuration actuelle de la CLI prend en charge 22 formats, dont HTML (.html et .htm), le texte brut (.txt, une unité par ligne, comme dans la v0), les tableaux CSV qui regroupent toutes les langues dans un seul fichier, à raison d’une colonne par langue, et les fichiers Java .properties (une unité par clé, comme dans la v0, avec lockedKeys, preservedKeys et ignoredKeys mis en correspondance comme dans la v0, et lockedPatterns en syntaxe RE2, qui ne prend en charge ni les assertions avant ou arrière ni les références arrière). Vérifiez qu’un fichier de compartiment csv de la v0 respecte la structure CSV avant de le déplacer. Vérifiez les chemins d’un compartiment properties de la v0 au regard des propriétés Java : un nom de fichier [locale] tel que messages_[locale].properties devient un motif source tel que messages_en.properties. Les compartiments CSV par langue, MJML et les autres compartiments propres à l’ancienne version nécessitent une conversion vérifiée ou une autre méthode de traduction. La section Configuration détaille les valeurs exactes de l’énumération, les règles de correspondance et les modèles de sortie. Les paramètres de modèle, d’invite et d’URL de base utilisés dans la v0 pour l’accès direct aux fournisseurs ne font pas partie de ce schéma de projet.
Examinez une source sélectionnée et les chemins cibles qui en découlent avant d’élargir la configuration. Pour les propriétés des formats de la famille Markdown, utilisez translateComponentProps.
Adopter et mettre à jour les traductions #
La planification actuelle à périmètre défini ou d’initialisation permet d’adopter les cibles existantes. Vérifiez un ensemble représentatif de fichiers et les modifications humaines avant d’établir cette référence : la seule présence d’un fichier ne permet pas de savoir si ses valeurs correspondent à la dernière version de la source.
Le remplissage rétroactif ajoute les fichiers ordinaires manquants, tandis que la v0 ajoute généralement les clés manquantes dans les catalogues existants. Pour ces opérations ultérieures, utilisez les mises à jour incrémentales actuelles de la source ou l’actualisation des clés prise en charge. Une clé JSON renommée constitue un nouveau travail fondé sur son chemin, même si son texte correspond à celui d’une ancienne clé ; ne comptez pas sur le mécanisme de la v0 qui réutilise les traductions après renommage grâce aux empreintes du contenu.
Les modifications apportées aux cibles dont les clés n’ont pas changé peuvent être conservées lors des opérations incrémentales. Les règles explicites de préservation des clés permettent de choisir séparément qui est responsable de leur gestion. Pour les formats à fichiers séparés, le mode forcé appliqué au fichier entier supprime le contexte de la cible actuelle et peut remplacer des formulations acceptées : ce n’est donc pas un raccourci pour l’adoption.
Terminer la première exécution avec la version actuelle #
Suivez le guide de démarrage rapide de la version actuelle jusqu’au remplissage rétroactif et à la récupération des fichiers. Un simple premier push sans référence enregistre les octets de la source au lieu de demander les traductions initiales. Attendez ou effectuez un pull avant de considérer le workflow des fichiers comme terminé.
Committez ensemble la source acceptée, la cible, la configuration et le Lockfile actuel. Le pointeur vers la dernière exécution reste local au répertoire personnel et n’est pas transféré via Git. Un pull ultérieur compare les empreintes ; committer une modification divergente à elle seule ne résout pas le conflit. lingo check remplace l’ancien contrôle de verrouillage figé au niveau des fichiers : il échoue si une source a changé depuis .lingo/lock.json ou si un fichier cible manque, et ne crée jamais de Lockfile manquant. Sans Lockfile committé, il ne peut pas détecter les modifications de la source et vérifie seulement que les fichiers cibles existent.
Migration React #
Le workflow React actuel extrait les appels contenant des littéraux de source et de contexte vers des fichiers JSONC et des déclarations, traduit les catalogues sélectionnés, puis charge une table de chaînes à l’exécution. Vérifiez le mécanisme de repli, les variables, le changement de langue et les formulations acceptées d’un composant avant d’étendre la modification.
Consultez Migrer les messages React existants et React pour les opérations propres au paquet. Le lingo guide migrate fourni correspond à la version installée ; il ne garantit pas la parité avec toutes les configurations générées antérieurement.