Périmètres de traduction
Sélectionnez des fichiers et des clés stables en distinguant les mises à jour incrémentales, la couverture des cibles et les actualisations volontaires.
Une modification de localisation peut concerner un fichier, une langue ou un ensemble de messages. La CLI sélectionne ces dimensions de différentes façons : la configuration du projet définit les fichiers et les langues cibles ; les motifs positionnels restreignent les fichiers et modifient la planification ; --key sélectionne les messages par clé stable.
Le périmètre des fichiers modifie la planification #
lingo push 'locales/en.json' --waitLe motif restreint la sélection des fichiers sources configurés. Pour un format à fichiers séparés, cette commande crée les cibles manquantes et laisse les cibles existantes inchangées, même si la source a changé. Si elle exclut certaines langues configurées de la tâche, elle conserve l'état de référence existant de la source pour qu'un push simple ultérieur puisse encore traiter ces modifications. Elle peut initialiser cet état de référence s'il n'existe pas encore.
Pour les modifications courantes de la source, utilisez simplement lingo push --wait. Pour remplacer volontairement un fichier entier dans un format à fichiers séparés, indiquez un périmètre positionnel avec --force, en gardant à l'esprit que le mode forcé supprime le contexte cible existant. Les catalogues XCStrings peuvent toujours réutiliser les traductions intégrées ; consultez les mises à jour des catalogues. Les cibles sont toujours définies par targetLocales ; push ne propose aucune option --locale ou --target-locale.
Actualisation par clé stable #
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --waitRépétez --key pour effectuer plusieurs sélections. Une clé est un chemin utilisant des points ou des crochets, comme checkout.title ou items[0].title. Sélectionner un objet inclut toutes les chaînes qu'il contient. Ainsi, auth.login inclut auth.login.title sans sélectionner auth.login_url. * représente un segment entier et [] chaque élément d'un tableau ; les caractères génériques partiels comme auth.log* sont refusés. Un motif commençant par $. ou $[ est transmis tel quel comme requête JSONPath. Placez les motifs contenant des caractères génériques entre guillemets.
Les motifs écrits pour l'ancienne CLI avec / fonctionnent également. Un motif contenant / est découpé uniquement au niveau de /, et chaque nom est traité comme un tout : auth/login sélectionne les mêmes clés que auth.login, et common/error.message sélectionne la clé error.message sous common. Les noms encodés en pourcentage, comme legal/Terms%20of%20use, sont décodés ; un motif sans / est un chemin à points et n'est pas décodé. Écrivez donc un nom encodé isolé en JSONPath, par exemple $['Terms of use']. Puisque tous les motifs contenant / sont interprétés de cette façon, une clé dont le nom contient / nécessite JSONPath, par exemple $.routes['/about'].title. Dans cette forme, * représente un nom entier, et un * final, comme dans auth/*, sélectionne les valeurs directement sous auth, mais pas les objets ou tableaux qui y sont imbriqués, comme le faisait l'ancienne CLI. Un /** final couvre tout ce qui se trouve sous le nom qui le précède : auth/** équivaut à auth, et auth/*/** couvre aussi les objets et tableaux sous auth que auth/* exclut. Un nombre comme items/0 sélectionne l'élément du tableau ou la clé d'objet "0", selon ce que contient le document. Les motifs génériques à l'intérieur d'un nom, ** ailleurs qu'à la fin, les crochets et les noms vides comme a//b sont refusés.
| Formats | Périmètre des clés |
|---|---|
| JSON/JSONC, PHP, TypeScript, fichiers de propriétés Java | Régénère les chaînes sélectionnées, même lorsque les valeurs sources sont inchangées. |
| YAML/YAML à clé racine | Sélectionne les clés stables, mais les chaînes sélectionnées inchangées peuvent réutiliser les traductions existantes. |
| gettext, ARB, Apple strings, XCStrings, CSV, Android, XLIFF | Non pris en charge ; --key interrompt le push avec une erreur. |
| Markdown, MDX, Markdoc, HTML, OpenAPI YAML, SubRip, texte brut, Apple stringsdict | Aucune clé stable ; formats ignorés avec un message. |
L'actualisation par clé nécessite des cibles existantes. Les langues manquantes et les formats sans clés stables sont ignorés avec des messages, plutôt qu'initialisés. Le remplissage rétroactif crée les fichiers ordinaires manquants, mais ne comble pas les lacunes dans les fichiers existants. L'ajout de --force ne modifie pas la planification par clé et n'empêche pas la réutilisation des traductions YAML.
L'actualisation par clé laisse inchangé l'état de référence de l'ensemble de la source, que push --wait ou un pull distinct récupère cette actualisation. Les modifications courantes de la source encore en attente sont donc toujours traitées lors du prochain push simple.
Actualiser après une modification des consignes #
Modifier le glossaire ou les règles d'un moteur de localisation ne change pas les octets des fichiers sources. Un push simple peut donc rester sans effet. Pour JSON, JSONC, TypeScript et PHP, sélectionnez les clés stables concernées. Pour YAML, modifiez directement la cible pour apporter une correction précise, ou sauvegardez les cibles acceptées et utilisez --force avec un périmètre couvrant des fichiers entiers, sans --key, pour les régénérer. Inspectez l'ensemble du fichier obtenu, car ce remplacement peut aussi modifier les messages voisins. Les contrôles des clés déterminent quelles valeurs sources ou cibles sont conservées lors de la reconstruction ; ils ne sélectionnent pas le travail à effectuer.
Pour une modification importante, choisissez un périmètre suffisamment restreint pour pouvoir l'inspecter et revenir en arrière, puis estimez-le avant de le soumettre. L'estimation téléverse les fichiers nécessaires et planifie le travail sans créer de tâche de traduction.
Retraduire une seule langue #
Pour un projet avec un fichier distinct par langue, supprimez les cibles de cette langue et effectuez un remplissage rétroactif des fichiers manquants. Terminez d'abord les mises à jour de la source en attente et sauvegardez les traductions acceptées. La purge filtrée conserve les états de référence de la source et les entrées du Lockfile pour les autres langues.
Pour une source configurée à l'emplacement locales/en.json, prévisualisez la suppression de la cible française :
lingo purge --locale fr --file locales/en.jsonVérifiez les chemins indiqués. S'ils correspondent aux cibles souhaitées, confirmez la suppression et créez les traductions manquantes :
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --waitPour une configuration utilisant des motifs génériques, comme locales/en/*.json, transmettez des chemins sources concrets en répétant l'option --file dans les deux commandes de purge. La purge ne développe pas elle-même les motifs génériques. Incluez chaque source dont vous souhaitez régénérer la cible française et vérifiez qu'aucun autre fichier cible ne manque avant le remplissage rétroactif : celui-ci crée toutes les cibles configurées manquantes.
Une fois l'opération terminée, inspectez le résultat en français et committez-le avec le Lockfile mis à jour. Les fichiers cibles existants des autres langues restent inchangés. Consultez Purge pour connaître les règles de sélection. Cette procédure ne s'applique pas aux catalogues XCStrings, où la source et toutes les langues cibles partagent un seul fichier.