Lockfile et cache
Gardez les références sources, les empreintes cibles, les artefacts distants et le pointeur local d’exécution en cohérence lors des mises à jour et de la récupération.
La traduction incrémentale doit pouvoir identifier ce qui a changé. .lingo/lock.json enregistre les empreintes des sources et des cibles ; le serveur conserve les artefacts et les traductions produites ; un pointeur stocké dans le répertoire personnel indique la dernière exécution dont les résultats sont à récupérer. Chacun répond à une opération distincte : supprimer l’un ne permet donc pas de résoudre tous les problèmes liés à l’autre.
La référence du projet #
Le Lockfile utilise la version 1 et une table files qui associe les chemins relatifs au dépôt à des empreintes SHA-256 :
{
"version": 1,
"files": {
"locales/en.json": {
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
}
}Cette empreinte illustre le format attendu ; ce n’est pas une valeur à copier. Les empreintes sources identifient les octets de la version précédente pour la comparaison incrémentale. Les empreintes cibles permettent de détecter les modifications locales avant la récupération. Le fichier ne contient ni texte traduit ni évaluation de la qualité.
Committez le Lockfile avec les modifications sources et cibles acceptées qu’il décrit. En l’absence d’état, push se comporte comme lors de l’établissement de la première référence ; si l’état est mal formé ou non pris en charge, l’opération échoue au lieu de le réinitialiser silencieusement.
Quand les empreintes sont mises à jour #
La récupération enregistre les empreintes des cibles terminées. Une soumission sans récupération ne finalise pas la référence. Chaque document est finalisé séparément : ses cibles restent en attente jusqu’à ce qu’elles soient toutes terminées. Une référence existante couvrant l’intégralité de la source n’est mise à jour que si le document couvre toutes les langues cibles configurées, que toutes les cibles sont terminées et qu’aucun périmètre de clés n’est défini. Une récupération limitée à certaines langues conserve cette référence pour les autres ; elle peut initialiser une entrée source s’il n’en existe pas. L’actualisation d’une clé laisse l’empreinte source inchangée, que push --wait ou pull en récupère le résultat.
Artefacts et traductions en cache #
Les artefacts sont adressés par leur contenu : push n’envoie donc que les octets dont le serveur ne dispose pas. Une source antérieure référencée par le Lockfile doit pouvoir être récupérée à partir des octets locaux ou du serveur. Si elle n’est disponible ni localement ni sur le serveur, examinez l’entrée correspondante du Lockfile et récupérez des octets dont la validité est établie, ou une référence cohérente. Ne remplacez pas l’empreinte par une valeur choisie au hasard.
Le cache des traductions produites est distinct du stockage des sources. Supprimer une cible locale ne garantit pas qu’une requête ultérieure fera à nouveau appel au modèle.
Le pointeur de la dernière exécution #
~/.lingo/runs/<project-hash>.json identifie le push le plus récent pour le chemin absolu de la racine d’un projet. Il contient les identifiants de l’exécution, de l’organisation et du moteur de localisation, ainsi que la langue source et l’heure de création. Tant que les résultats du push n’ont pas été récupérés, il conserve aussi l’identité de la requête : un push répété peut ainsi réutiliser la soumission plutôt que la dupliquer.
Ce pointeur n’est pas .lingo/run.json et n’est pas transmis avec Git. Un checkout déplacé ou un autre agent d’exécution peut ne pas en disposer, même avec une configuration et un Lockfile identiques. Un nouveau push peut le remplacer. Conservez l’identité de l’exécution d’origine dans des registres opérationnels non secrets jusqu’à la fin de la récupération.
Conserver une exécution pour une autre tâche CI #
Si vous devez attendre une relecture ou séparer la soumission et la récupération en deux tâches, conservez le pointeur avant que l’agent d’exécution chargé de la soumission ne disparaisse. Exécutez ceci depuis le répertoire absolu contenant le .lingo/config.json voulu, immédiatement après la soumission et avant tout autre push :
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
const root = process.cwd();
if (!existsSync(".lingo/config.json")) throw new Error("Run from the configured project root");
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
mkdirSync(".lingo-ci", { recursive: true });
copyFileSync(join(homedir(), ".lingo", "runs", `${hash}.json`), ".lingo-ci/run.json");
writeFileSync(".lingo-ci/project-root.txt", root);
JSCes deux fichiers contiennent le pointeur d’exécution non secret et le chemin absolu exact de la racine du projet utilisé pour le localiser. Vérifiez que runId dans le JSON exporté correspond à l’identifiant affiché lors de cette soumission ; un ancien pointeur peut subsister si la soumission échoue avant l’enregistrement d’une nouvelle exécution. Conservez les fichiers vérifiés comme artefacts de tâche à accès contrôlé, avec la révision source, .lingo/config.json, .lingo/lock.json et les fichiers sources et cibles correspondants, y compris les fichiers produits non committés. Pour les exemples CI à un seul fichier, conservez locales/en.json et locales/es.json ; pour un autre projet, utilisez les chemins effectivement sélectionnés. Conservez l’intégralité du catalogue partagé lorsque la source et les cibles utilisent un seul fichier. Prévoyez une durée de conservation des artefacts suffisante pour la relecture et la récupération. N’archivez jamais l’intégralité de ~/.lingo, les fichiers d’identifiants ou les valeurs secrètes des variables d’environnement.
Après la relecture, restaurez la même révision et l’état des fichiers conservés à la même racine absolue du projet sur un agent d’exécution autorisé. Installez la même version de la CLI et fournissez les identifiants séparément via son mécanisme de gestion des secrets. Depuis cette racine, restaurez uniquement ce pointeur :
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
const root = readFileSync(".lingo-ci/project-root.txt", "utf8");
if (process.cwd() !== root || !existsSync(".lingo/config.json")) {
throw new Error("Restore the configured project at its original absolute root");
}
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
const directory = join(homedir(), ".lingo", "runs");
mkdirSync(directory, { recursive: true });
const destination = join(directory, `${hash}.json`);
if (existsSync(destination)) throw new Error("Preserve the existing run pointer before replacing it");
copyFileSync(".lingo-ci/run.json", destination);
JS
lingo pull --dry-runVérifiez que l’exécution indiquée est bien celle que vous avez conservée, résolvez les éventuels conflits, puis utilisez lingo pull et examinez les résultats récupérés. N’effectuez pas de push au préalable : il remplacerait le pointeur. Si le service CI ne peut pas recréer la racine d’origine, utilisez un agent d’exécution autorisé et persistant disposant de ce chemin pour la soumission et la récupération ; copier le pointeur dans un checkout situé ailleurs ne suffit pas. Ne supprimez l’export temporaire .lingo-ci qu’une fois la récupération et la conservation opérationnelle terminées, et ne l’incluez pas dans les commits de traduction.
Traductions existantes et modifications humaines #
La planification à périmètre limité ou d’initialisation peut reprendre les cibles existantes. Vérifiez d’abord leur langue et leur exhaustivité : des textes provisoires dans la langue source peuvent satisfaire un contrôle de présence sans constituer des traductions. Le Remplissage rétroactif crée les fichiers ordinaires manquants, mais pas les clés manquantes dans un fichier existant.
Le traitement incrémental normal transmet les modifications cibles associées aux clés inchangées afin de les préserver. Les clés sources modifiées peuvent remplacer ces modifications. JSON utilise les chemins des clés comme identifiants : renommer une clé crée donc du travail supplémentaire, même si le texte source est identique. Ce fonctionnement diffère de la réutilisation fondée sur les empreintes de contenu de la v0.
preservedKeys ajoute une protection explicite lorsque le texte cible doit faire autorité, mais le forçage sur l’ensemble du fichier supprime le contexte de la cible actuelle nécessaire à cette protection. Pull compare les nouvelles empreintes avant d’écrire ; un commit Git à lui seul ne change pas cette comparaison. Évitez de modifier les cibles pendant une récupération directe avec push --wait.
Branches et accès en écriture partagés #
| Organisation | Conséquence |
|---|---|
| Traduction dans la branche de fonctionnalité | Relisez la source et la cible ensemble ; réconciliez les modifications concurrentes de la référence lors des rebases. |
| PR de traduction après la fusion des sources | Relecture séparée, avec un délai avant l’acceptation des modifications traduites. |
| PR de traduction de la GitHub App | L’intégration contrôle les déclencheurs et l’écriture des résultats ; l’approbation de l’exécution est distincte de la fusion. |
| Un agent d’exécution autorisé écrit directement dans une branche | Nécessite une autorisation d’écriture explicite, des contrôles de contenu et une protection contre les accès en écriture concurrents. |
En cas de conflit de fusion du Lockfile, identifiez d’abord les révisions sources et cibles décrites de chaque côté. Réconciliez le contenu accepté, puis conservez ou reconstruisez une référence cohérente via le workflow approprié. Combiner des empreintes sans rapport entre elles ou supprimer le Lockfile pour faire disparaître un conflit peut masquer une traduction inachevée.
Pour configurer le fournisseur, consultez GitHub App, GitHub Actions, GitLab, Bitbucket ou Buildkite. check compare les sources configurées à ce Lockfile et signale les fichiers cibles manquants. Sauf dans les catalogues React .jsonc, cette commande ne vérifie pas les clés contenues dans ces fichiers.
Autres états stockés dans le répertoire personnel #
~/.lingo/update-check.json met en cache les vérifications de version pendant 24 heures. Les identifiants et l’identité de télémétrie anonyme sont stockés séparément. Aucun de ces éléments ne contient les fichiers traduits produits. Consultez Dépannage pour identifier l’opération qui a échoué avant de supprimer un état.