Lockfile y caché
Mantén vinculados las referencias de origen, los hashes de destino, los artefactos remotos y el puntero local de ejecución durante las actualizaciones y la recuperación.
La traducción incremental necesita saber qué ha cambiado. .lingo/lock.json registra los hashes de origen y destino; el servidor conserva los artefactos y los resultados de traducción; un puntero local en el directorio personal identifica la última ejecución cuyos resultados hay que recoger. Cada elemento cumple una función distinta, por lo que eliminar uno no sirve como solución general para reparar otro.
La referencia del proyecto #
El Lockfile utiliza la versión 1 y un mapa files que asocia rutas relativas al repositorio con hashes SHA-256:
{
"version": 1,
"files": {
"locales/en.json": {
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
}
}Este hash muestra el formato, no un valor que debas copiar. Los hashes de origen identifican los bytes anteriores para la comparación incremental. Los hashes de destino ayudan a detectar modificaciones locales antes de recoger los resultados. El archivo no contiene texto traducido ni evaluaciones de calidad.
Incluye el Lockfile en el commit junto con los cambios de origen y destino aceptados que describe. Si falta el estado, push se comporta como al establecer la primera referencia; si el estado está mal formado o no es compatible, la operación falla en lugar de restablecerlo sin avisar.
Cuándo se actualizan los hashes #
La recogida de resultados registra los hashes de los destinos completados. El envío por sí solo, sin recoger los resultados, no consolida la referencia. Cada documento se consolida por separado y retiene los demás destinos hasta que todos estén completos. Una referencia existente del origen completo solo se actualiza cuando el documento abarca todos los idiomas de destino configurados, todos los destinos están completos y no se ha delimitado un conjunto de claves. Recoger los resultados de solo algunos idiomas mantiene esa referencia para los demás; también puede inicializar una entrada de origen si aún no existe. Una actualización de claves deja el hash de origen sin cambios, tanto si los resultados se recogen con push --wait como con pull.
Artefactos y traducciones en caché #
Los artefactos se identifican por su contenido, por lo que push solo sube los bytes que le faltan al servidor. Un origen anterior indicado en el Lockfile debe poder recuperarse a partir de los bytes locales o del servidor. Si no está disponible en ninguno de los dos, revisa la entrada correspondiente del Lockfile y recupera bytes cuya validez esté confirmada o una referencia coherente. No lo sustituyas por un hash elegido a ojo.
Los resultados de traducción en caché son distintos del almacenamiento del origen. Eliminar un destino local no garantiza que una solicitud posterior vuelva a invocar el modelo desde cero.
El puntero a la última ejecución #
~/.lingo/runs/<project-hash>.json identifica el push más reciente para la ruta absoluta de la raíz de un proyecto. Incluye los ID de la ejecución, la organización y el motor de localización, el idioma de origen y la fecha y hora de creación. Hasta que se recogen los resultados de ese push, también conserva la identidad de la solicitud, lo que permite que un push repetido reutilice el envío en lugar de duplicarlo.
Este puntero no es .lingo/run.json y no se transfiere con Git. Un checkout trasladado u otro ejecutor pueden carecer del puntero incluso con una configuración y un Lockfile idénticos. Un nuevo push puede sustituirlo. Conserva la identidad de la ejecución original en registros operativos sin secretos hasta que termine la recuperación.
Conservar una ejecución para otro trabajo de CI #
Si hay que esperar a una revisión o separar el envío y la recuperación en distintos trabajos, conserva el puntero antes de que desaparezca el ejecutor que realiza el envío. Ejecuta lo siguiente desde la ruta absoluta del directorio que contiene el .lingo/config.json que quieres utilizar, inmediatamente después del envío y antes de otro 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);
JSEstos dos archivos contienen el puntero de ejecución sin secretos y la ruta absoluta exacta de la raíz del proyecto utilizada para localizarlo. Comprueba que runId en el JSON exportado coincide con el ID mostrado por este envío; puede quedar un puntero anterior si el envío falla antes de registrar una nueva ejecución. Conserva los archivos verificados como artefactos del trabajo con acceso controlado, junto con la revisión del código fuente, .lingo/config.json, .lingo/lock.json y los archivos de origen y destino correspondientes, incluidos los resultados aún no guardados en un commit. Para los ejemplos de CI de un solo archivo, conserva locales/en.json y locales/es.json; para otro proyecto, utiliza las rutas realmente seleccionadas. Conserva el catálogo compartido completo cuando el origen y los destinos utilicen un único archivo. Configura un periodo de conservación de los artefactos suficiente para la revisión y la recogida de resultados. Nunca archives todo ~/.lingo, archivos de credenciales ni valores secretos de variables de entorno.
Tras la revisión, restaura la misma revisión y el estado de los archivos conservados en la misma raíz absoluta del proyecto, en un ejecutor autorizado. Instala la misma versión de la CLI y proporciona las credenciales por separado mediante su mecanismo de gestión de secretos. Desde esa raíz, restaura únicamente este puntero:
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-runConfirma que la ejecución indicada es la que has conservado, resuelve cualquier conflicto y, después, utiliza lingo pull y revisa los resultados recuperados. No ejecutes push primero, porque sustituye el puntero. Si el servicio de CI no puede recrear la raíz original, utiliza un ejecutor autorizado persistente con esa ruta para el envío y la recuperación; no basta con copiar el puntero a un checkout ubicado en otra ruta. Elimina la exportación temporal .lingo-ci solo cuando hayan terminado la recogida de resultados y el periodo de conservación operativa, y no la incluyas en los commits de traducción.
Traducciones existentes y modificaciones humanas #
La planificación con un alcance delimitado o de inicialización puede adoptar los destinos existentes. Comprueba primero su idioma y si están completos: los textos provisionales en el idioma de origen pueden superar una comprobación de presencia sin ser traducciones. El proceso de completar lo que falta crea archivos ordinarios ausentes, pero no añade claves ausentes dentro de un archivo existente.
El trabajo incremental normal incorpora las modificaciones de destino de las claves sin cambios para conservarlas. Los cambios en las claves de origen pueden sustituir esas modificaciones. JSON utiliza las rutas de las claves como identidades, por lo que cambiar el nombre de una clave genera trabajo nuevo aunque el texto de origen sea idéntico; esto difiere de la reutilización mediante huellas de contenido de v0.
preservedKeys añade una protección explícita cuando el texto de destino debe seguir siendo la referencia válida, pero forzar el archivo completo elimina el contexto del destino actual necesario para esa protección. Pull compara hashes recién calculados antes de escribir; un commit de Git por sí solo no cambia esa comparación. Evita modificar los destinos durante la recogida directa de resultados con push --wait.
Ramas y procesos de escritura compartidos #
| Modalidad | Consecuencia |
|---|---|
| Traducir en la rama de la funcionalidad | Revisa el origen y el destino juntos; concilia las modificaciones contrapuestas de la referencia al reorganizar los commits. |
| PR de traducción tras fusionar el origen | Revisión independiente, con un intervalo antes de aceptar los cambios traducidos. |
| PR de traducción de GitHub App | La integración controla los desencadenantes y la escritura de resultados; la aprobación de la ejecución es independiente de la fusión. |
| Un ejecutor autorizado escribe directamente en una rama | Requiere autorización explícita de escritura, comprobaciones del contenido y protección frente a procesos de escritura simultáneos. |
Si se produce un conflicto de fusión en el Lockfile, identifica primero las revisiones de origen y destino que describe cada parte. Concilia el contenido aceptado y, después, conserva o reconstruye una referencia coherente mediante el flujo de trabajo adecuado. Combinar hashes sin relación entre sí o eliminar el Lockfile para silenciar un conflicto puede ocultar traducciones sin terminar.
La configuración del proveedor se realiza en GitHub App, GitHub Actions, GitLab, Bitbucket o Buildkite. check compara las fuentes configuradas con este Lockfile e indica qué archivos de destino faltan. Fuera de los catálogos de React .jsonc, no comprueba las claves que contienen.
Otros datos de estado locales en el directorio personal #
~/.lingo/update-check.json almacena en caché las comprobaciones de versión durante 24 horas. Las credenciales y la identidad de telemetría anónima se almacenan por separado. Ninguno de estos elementos guarda los archivos traducidos resultantes. Consulta Resolución de problemas para identificar la operación que ha fallado antes de eliminar datos de estado.