Archivo de bloqueo i18n.lock

i18n.lock es un archivo de bloqueo que rastrea las sumas de verificación del contenido para evitar retraducciones innecesarias y optimizar el rendimiento de Lingo.dev CLI.

i18n.lock almacena las sumas de verificación del contenido fuente y las claves de traducción para identificar qué ha cambiado entre ejecuciones de traducción. Como resultado, solo se traduce el contenido nuevo o modificado, reduciendo el tiempo de procesamiento y los costos de traducción.

Estructura del archivo de bloqueo

i18n.lock utiliza un formato YAML estructurado para almacenar las sumas de verificación del contenido:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    key: f8692d39317193acf0e2e47172703c46
  b18975fb19122ebb67g0ef817641f553:
    key: g9703e40428204bdf1f3f58283814d57

Elementos de configuración:

  • version — Versión del esquema del archivo de bloqueo para compatibilidad de migración
  • checksums — Mapa de sumas de verificación de contenido a sumas de verificación de claves que rastrea el contenido traducido
  • checksums.[content-hash] — Hash SHA-256 del contenido fuente que sirve como identificador único
  • checksums.[content-hash].key — Hash SHA-256 de la clave de traducción que permite la detección de cambios de nombre de claves

Lingo.dev CLI preserva las traducciones existentes cuando detecta contenido idéntico con diferentes sumas de verificación de claves. No se produce retraducción, manteniendo la consistencia de la traducción mientras permite cambios en la organización de claves. Lee más sobre cambio de nombre de claves.

Integración del flujo de trabajo

i18n.lock opera automáticamente durante los flujos de trabajo de traducción:

Primera ejecución — Crea el archivo de bloqueo con las sumas de verificación iniciales del contenido:

npx lingo.dev@latest run
# Creates i18n.lock with all source content checksums

Recrear archivo de bloqueo — Recrea el archivo de bloqueo desde cero:

npx lingo.dev@latest lockfile --force
# Recreates i18n.lock with all source content checksums

Consejo: Puedes usar este comando de forma segura para restablecer el archivo de bloqueo a su estado real durante la resolución de conflictos de fusión. La deduplicación también se ejecuta automáticamente en cada carga; consulta Deduplicación del archivo de bloqueo.

Ejecuciones posteriores — Procesa solo el contenido modificado:

npx lingo.dev@latest run
# Compares current content against i18n.lock
# Translates only new or modified content

Forzar retraducción — Omite la optimización del archivo de bloqueo y retraduce todo el contenido, recreando el archivo de bloqueo:

npx lingo.dev@latest run --force
# Ignores i18n.lock and retranslates all content

Verificación congelada — Valida la integridad de la traducción:

npx lingo.dev@latest run --frozen
# Fails if any content requires translation
# Used in CI/CD to ensure complete translations

Deduplicación del archivo de bloqueo

El YAML del archivo de bloqueo puede contener claves de traducción duplicadas bajo el mismo bloque de suma de verificación. Los analizadores YAML estándar conservan solo la última aparición, lo que puede llevar a un seguimiento perdido y conflictos de fusión difíciles de resolver manualmente.

Lingo.dev CLI está diseñado para mantener un estado consistente del archivo de bloqueo. Deduplica el archivo de bloqueo automáticamente cada vez que se carga. Las claves duplicadas bajo un bloque de suma de verificación se detectan y eliminan; se conserva la última aparición (última escritura gana, coincidiendo con el comportamiento común de fusión). Como resultado, el archivo de bloqueo permanece internamente consistente y coincide con lo que se escribe de vuelta.

Cuándo se ejecuta — La deduplicación se ejecuta en cada carga, incluyendo:

  • npx lingo.dev@latest run
  • npx lingo.dev@latest pull
  • npx lingo.dev@latest push
  • npx lingo.dev@latest status
  • npx lingo.dev@latest lockfile

Si se eliminan duplicados, el CLI registra un mensaje como: Removed 3 duplicate entries from i18n.lock. No se requiere ninguna acción del usuario; el paso es idempotente y seguro para ejecutar en cada carga. Para problemas de fusión difíciles o recurrentes, aún puedes usar npx lingo.dev@latest lockfile --force para recrear el archivo de bloqueo desde cero.

Ejemplo — Después de fusionar dos ramas que ambas cambiaron las mismas claves:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    greeting.hello: abc123
    greeting.goodbye: def456
    greeting.hello: xyz789
    button.submit: ghi012
    button.submit: jkl345

Al cargar, el CLI deduplica y conserva la última aparición de cada clave:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    greeting.goodbye: def456
    greeting.hello: xyz789
    button.submit: jkl345

Se eliminan dos entradas duplicadas.

Integración con control de versiones

i18n.lock debe confirmarse en el control de versiones junto con los archivos de traducción.

El archivo de bloqueo es una parte esencial del sistema de traducción incremental de Lingo.dev CLI, lo que lo hace práctico para proyectos de cualquier tamaño.