Lockfile y caché

Mantén vinculados las líneas base del contenido fuente, 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é cambió. .lingo/lock.json registra los hashes del contenido fuente y de destino; el servidor conserva los artefactos y los resultados de traducción; un puntero local en el directorio de inicio identifica la ejecución más reciente cuyos resultados se deben recuperar. Cada elemento sirve para una operación distinta, así que eliminar uno no es una solución general para corregir problemas en otro.

La línea base del proyecto #

El Lockfile usa la versión 1 y un mapa files que vincula las rutas relativas al repositorio con hashes SHA-256:

json
{
  "version": 1,
  "files": {
    "locales/en.json": {
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  }
}

Este hash muestra el formato; no es un valor que debas copiar. Los hashes del contenido fuente identifican los bytes anteriores para la comparación incremental. Los hashes de destino ayudan a detectar cambios locales antes de recuperar los resultados. El archivo no contiene texto traducido ni evaluaciones de calidad.

Incluye el Lockfile en el commit junto con los cambios aceptados del contenido fuente y de destino que describe. Si falta el estado, push actúa como si estuviera estableciendo la primera línea base; si el estado tiene un formato incorrecto o no es compatible, la operación falla en lugar de restablecerlo sin avisar.

Cuándo se actualizan los hashes #

La recuperación de resultados registra los hashes de los destinos completados. El envío sin recuperación no consolida la línea base. Cada documento se consolida por separado, y los destinos del mismo documento se retienen hasta que todos estén completos. Una línea base existente de todo el contenido fuente solo se actualiza cuando el documento abarca todos los idiomas de destino configurados, todos los destinos están completos y no se ha definido un alcance de claves. Recuperar resultados solo para algunos idiomas conserva esa línea base para los demás; también puede inicializar una entrada del contenido fuente si aún no existe. Una actualización de claves deja el hash del contenido fuente sin cambios, tanto si los resultados se recuperan con push --wait como con pull.

Artefactos y traducciones en caché #

Los artefactos se identifican por su contenido, por lo que push solo carga los bytes que le faltan al servidor. Una versión anterior del contenido fuente indicada en el Lockfile debe poder recuperarse de los bytes locales o del servidor. Si ninguno de los dos la tiene, revisa la entrada indicada en el Lockfile y recupera bytes cuya validez esté confirmada o una línea base coherente. No uses un hash estimado como sustituto.

Los resultados de traducción en caché son distintos del almacenamiento del contenido fuente. Eliminar un archivo de destino local no garantiza que una solicitud posterior vuelva a invocar el modelo desde cero.

El puntero a la ejecución más reciente #

~/.lingo/runs/<project-hash>.json identifica el push más reciente para una ruta absoluta de la raíz del 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 recuperan los resultados del push, también conserva la identidad de la solicitud, que permite reutilizar el envío si se repite el push, en lugar de duplicarlo.

Este puntero no es .lingo/run.json y no se transfiere con Git. Un checkout movido a otra ubicación o un ejecutor distinto pueden no tener el puntero, incluso con la misma configuración y el mismo Lockfile. Un nuevo push puede reemplazarlo. Conserva la identidad de la ejecución original en registros operativos sin secretos hasta que termine la recuperación.

Conserva una ejecución para otro trabajo de CI #

Si debes esperar 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 previsto, inmediatamente después del envío y antes de otro push:

sh
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);
JS

Estos dos archivos contienen el puntero de ejecución sin secretos y la ruta absoluta exacta de la raíz del proyecto que se usó para localizarlo. Comprueba que runId en el JSON exportado coincida con el ID que muestra 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 contenido fuente, .lingo/config.json, .lingo/lock.json y los archivos de origen y destino correspondientes, incluidos los resultados que aún no se hayan incluido en un commit. Para los ejemplos de CI de un solo archivo, conserva locales/en.json y locales/es.json; para otro proyecto, usa las rutas seleccionadas en ese proyecto. Conserva todo el catálogo compartido cuando el contenido fuente y los destinos usen un mismo archivo. Configura un período de retención de artefactos lo suficientemente largo para la revisión y la recuperación. Nunca archives todo ~/.lingo, archivos de credenciales ni valores secretos de variables de entorno.

Después de la revisión, restaura la misma revisión y el estado de los archivos conservados en la misma ruta absoluta de la raíz del proyecto, en un ejecutor autorizado. Instala la misma versión de la CLI y proporciona las credenciales por separado mediante su mecanismo de secretos. Desde esa raíz, restaura únicamente este puntero:

sh
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-run

Confirma que la ejecución indicada sea la que conservaste, resuelve cualquier conflicto y luego usa lingo pull y revisa los resultados recuperados. No ejecutes push primero, porque eso reemplaza el puntero. Si el servicio de CI no puede recrear la raíz original, usa 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 después de completar la recuperación y la retención operativa, y mantenla fuera de los commits de traducción.

Traducciones existentes y ediciones humanas #

La planificación con alcance limitado o de inicialización puede adoptar los destinos existentes. Primero comprueba su idioma y que estén completos: el texto provisional en el idioma de origen puede pasar una comprobación de presencia sin ser una traducción. El proceso de completar lo que falta crea archivos normales ausentes, pero no agrega claves faltantes dentro de un archivo existente.

El trabajo incremental normal proporciona las ediciones de destino de las claves que no cambiaron para conservarlas. Los cambios en las claves del contenido fuente pueden reemplazar esas ediciones. JSON usa las rutas de las claves como identificadores, por lo que cambiar el nombre de una clave genera trabajo nuevo aunque el texto fuente sea idéntico; esto difiere de la reutilización basada en huellas digitales del contenido de v0.

preservedKeys agrega 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 editar los destinos durante la recuperación directa con push --wait.

Ramas y procesos de escritura compartidos #

ModalidadConsecuencia
Traducir en la rama de la funcionalidadRevisa el contenido fuente y el de destino juntos; concilia las ediciones de la línea base que entren en conflicto durante los rebases.
PR de traducción después de integrar el contenido fuenteRevisión por separado, con un intervalo antes de que se acepten los cambios traducidos.
PR de traducción de GitHub AppLa integración controla los desencadenantes y la escritura de resultados; la aprobación de la ejecución es independiente de la integración de cambios.
Un ejecutor autorizado escribe directamente en una ramaRequiere autorización explícita de escritura, comprobaciones de contenido y protección contra procesos de escritura simultáneos.

Si hay un conflicto al integrar el Lockfile, primero identifica las revisiones del contenido fuente y de destino que describe cada lado. Concilia el contenido aceptado y luego conserva o reconstruye una línea base coherente mediante el flujo de trabajo adecuado. Combinar hashes no relacionados o eliminar el Lockfile para silenciar un conflicto puede ocultar traducciones pendientes.

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. Solo verifica las claves dentro de los archivos cuando se trata de catálogos de React .jsonc.

Otros datos de estado locales en el directorio de inicio #

~/.lingo/update-check.json guarda en caché las comprobaciones de versión durante 24 horas. Las credenciales y la identidad de telemetría anónima se guardan por separado. Ninguno de estos datos contiene los resultados de los archivos traducidos. Usa Solución de problemas para identificar la operación que falló antes de eliminar datos de estado.