i18n.lock Lockfile

i18n.lock — это lockfile, который отслеживает контрольные суммы контента, чтобы избежать лишних повторных переводов и ускорить работу Lingo.dev CLI.

i18n.lock хранит контрольные суммы исходного контента и ключей перевода, чтобы определить, что изменилось между запусками перевода. В результате переводится только новый или изменённый контент, что сокращает время обработки и расходы на перевод.

Структура lockfile

i18n.lock использует структурированный YAML-формат для хранения контрольных сумм контента:

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

Элементы конфигурации:

  • version — версия схемы lockfile для совместимости при миграциях
  • checksums — карта контрольных сумм контента и ключей, отслеживающая переведённый контент
  • checksums.[content-hash] — SHA-256 хеш исходного контента, служащий уникальным идентификатором
  • checksums.[content-hash].key — SHA-256 хеш ключа перевода, позволяющий отслеживать переименование ключей

Lingo.dev CLI сохраняет существующие переводы, если обнаруживает одинаковый контент с разными контрольными суммами ключей. Повторный перевод не выполняется, что поддерживает консистентность переводов и позволяет менять структуру ключей. Подробнее читайте о переименовании ключей.

Интеграция в рабочий процесс

i18n.lock работает автоматически в процессе перевода:

Первый запуск — создаёт lockfile с начальными контрольными суммами:

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

Пересоздать lockfile — полностью пересоздаёт lockfile с нуля:

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

Совет: эту команду можно спокойно использовать для сброса lockfile к актуальному состоянию при разрешении конфликтов слияния. Дедупликация также выполняется автоматически при каждой загрузке; см. Дедупликация lockfile.

Последующие запуски — обрабатывается только изменённый контент:

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

Принудительный повторный перевод — игнорирует оптимизацию lockfile и переводит весь контент заново, пересоздавая lockfile:

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

Проверка заморозки — проверяет полноту перевода:

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

Дедупликация lockfile

YAML-файл lockfile может содержать дублирующиеся ключи перевода в одном блоке контрольной суммы. Стандартные YAML-парсеры сохраняют только последнее вхождение, из-за чего может теряться отслеживание и возникать сложные для ручного решения конфликты слияния.

Lingo.dev CLI создан для поддержания консистентного состояния lockfile. Он автоматически дедуплицирует lockfile при каждой загрузке. Дублирующиеся ключи в блоке контрольной суммы обнаруживаются и удаляются; сохраняется последнее вхождение (last-write-wins, как обычно при слиянии). В итоге lockfile остаётся внутренне согласованным и соответствует тому, что записывается обратно.

Когда выполняется — дедупликация происходит при каждой загрузке, включая:

  • 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

Если дубликаты удаляются, CLI пишет сообщение вроде: Removed 3 duplicate entries from i18n.lock. Никаких действий от пользователя не требуется; этот шаг идемпотентен и безопасен для каждого запуска. Для сложных или повторяющихся конфликтов слияния всё равно можно использовать npx lingo.dev@latest lockfile --force, чтобы пересоздать lockfile с нуля.

Пример — после слияния двух веток, в которых изменялись одни и те же ключи:

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

При загрузке CLI дедуплицирует и оставляет последнее вхождение каждого ключа:

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

Два дубликата удалены.

Интеграция с системой контроля версий

i18n.lock должен коммититься в систему контроля версий вместе с файлами перевода.

Lockfile — это важная часть системы инкрементального перевода Lingo.dev CLI, которая делает её удобной для проектов любого размера.