Lockfile и кеш

Сохраняйте связь между базовыми состояниями исходников, хешами переводов, удалёнными артефактами и локальным указателем запуска при обновлении и восстановлении.

Для инкрементального перевода нужно знать, что изменилось. .lingo/lock.json хранит хеши исходников и переводов, сервер — артефакты и результаты перевода, а указатель в домашнем каталоге определяет последний запуск, результаты которого нужно получить. Каждый компонент отвечает за свою задачу, поэтому удаление одного — не универсальный способ исправить другой.

Базовое состояние проекта #

Lockfile использует версию 1 и карту files, которая сопоставляет пути относительно корня репозитория с хешами SHA-256:

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

Этот хеш приведён для примера — копировать его значение не нужно. Хеши исходников определяют прежнее содержимое для инкрементального сравнения. Хеши переводов помогают обнаружить локальные правки перед получением результатов. Файл не содержит ни переведённого текста, ни оценки качества.

Добавляйте Lockfile в коммит вместе с принятыми изменениями исходников и переводов, которые он описывает. Если данных о состоянии нет, push работает как при создании первого базового состояния. Если данные повреждены или их формат не поддерживается, push завершается ошибкой, а не сбрасывает их без предупреждения.

Когда обновляются хеши #

При получении результатов записываются хеши завершённых переводов. Отправка без получения результатов не фиксирует базовое состояние. Для каждого документа оно фиксируется отдельно: переводы на целевые локали не выдаются, пока не готовы все переводы документа. Существующее базовое состояние всего исходника обновляется, только если документ охватывает все настроенные целевые локали, все переводы завершены и область видимости ключей не задана. При получении результатов лишь для части локалей это базовое состояние сохраняется для остальных. Если записи исходника ещё нет, она может быть создана. Обновление отдельных ключей не меняет хеш исходника независимо от того, получены ли результаты через push --wait или pull.

Артефакты и кешированные переводы #

Артефакты адресуются по содержимому, поэтому push загружает только те байты, которых ещё нет на сервере. Прежняя версия исходника, указанная в Lockfile, должна быть доступна для восстановления из локальных данных или с сервера. Если её нет ни там ни там, проверьте соответствующую запись в Lockfile и восстановите заведомо корректное содержимое или согласованное базовое состояние. Не подставляйте хеш наугад.

Кеш результатов перевода — не то же самое, что хранилище исходников. Удаление локального файла перевода не гарантирует, что следующий запрос заново вызовет модель.

Указатель последнего запуска #

~/.lingo/runs/<project-hash>.json определяет последний push для абсолютного пути к корню проекта. Он содержит ИД запуска, организации и движка локализации, исходную локаль и время создания. Пока результаты push не получены, он также хранит идентификатор запроса: благодаря ему повторный push использует уже отправленный запрос, а не создаёт дубликат.

Это не .lingo/run.json: указатель не переносится вместе с Git. После перемещения checkout или на другом раннере указателя может не быть, даже если конфигурация и Lockfile совпадают. Новый push может его заменить. Пока получение результатов не завершено, сохраняйте исходный идентификатор запуска в рабочих записях, не содержащих секретных данных.

Как сохранить запуск для другого задания CI #

Если нужно дождаться проверки или разделить отправку и получение результатов между заданиями, сохраните указатель, пока раннер, отправивший запрос, ещё доступен. Сразу после отправки и до следующего push выполните эту команду из каталога с нужным .lingo/config.json, указав абсолютный путь к каталогу:

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

Эти два файла содержат указатель запуска без секретных данных и точный абсолютный путь к корню проекта, по которому находится указатель. Проверьте, что runId в экспортированном JSON совпадает с ИД, выведенным при этой отправке. Если отправка завершилась ошибкой до записи нового запуска, мог сохраниться прежний указатель. Сохраните проверенные файлы как артефакты задания с ограниченным доступом вместе с ревизией исходников, .lingo/config.json, .lingo/lock.json и соответствующими файлами исходников и переводов, включая результаты, не добавленные в коммит. Для примеров CI с одним файлом сохраните locales/en.json и locales/es.json. Для другого проекта используйте фактически выбранные пути. Если исходник и переводы хранятся в одном файле, сохраните весь общий каталог переводов. Задайте срок хранения артефактов, достаточный для проверки и получения результатов. Никогда не архивируйте весь ~/.lingo, файлы учётных данных или секретные значения переменных окружения.

После проверки восстановите ту же ревизию и сохранённое состояние файлов на авторизованном раннере, по тому же абсолютному пути к корню проекта. Установите ту же версию CLI и отдельно передайте учётные данные через механизм секретов раннера. Из корня проекта восстановите только этот указатель:

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

Убедитесь, что показан именно сохранённый запуск, устраните конфликты, затем выполните lingo pull и проверьте полученные результаты. Не выполняйте push перед этим: он заменит указатель. Если сервис CI не может воссоздать исходный корневой каталог, используйте для отправки и получения результатов постоянный авторизованный раннер с этим путём. Просто скопировать указатель в checkout по другому пути недостаточно. Удаляйте временный экспорт .lingo-ci только после получения результатов и окончания срока хранения рабочих записей. Не добавляйте его в коммиты с переводами.

Существующие переводы и ручные правки #

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

При обычном инкрементальном переводе правки целевого текста для неизменившихся ключей передаются, чтобы сохранить их. Если исходный ключ изменился, эти правки могут быть заменены. В JSON ключи определяются по их путям, поэтому переименование ключа создаёт новую задачу, даже если исходный текст остался тем же. Это отличается от повторного использования по отпечатку содержимого в v0.

preservedKeys позволяет явно защитить целевой текст, если он должен оставаться приоритетным. Но принудительная обработка всего файла убирает контекст текущего перевода, необходимый для этой защиты. Перед записью pull сравнивает актуальные хеши. Сам по себе коммит Git не меняет результат этого сравнения. Не редактируйте переводы во время прямого получения результатов через push --wait.

Ветки и совместная запись #

ПодходПоследствия
Перевод в ветке разработкиПроверяйте исходник и перевод вместе. При перебазировании согласовывайте конфликтующие правки базового состояния.
PR с переводом после слияния исходниковОтдельная проверка и пауза до принятия изменений в переводах.
PR с переводом от GitHub AppИнтеграция управляет условиями запуска и записью результатов. Одобрение запуска и слияние выполняются отдельно.
Авторизованный раннер записывает результаты прямо в веткуНужны явное разрешение на запись, проверки содержимого и защита от одновременной записи из нескольких источников.

При конфликте слияния Lockfile сначала определите, какие ревизии исходников и переводов описывает каждая сторона. Согласуйте принятое содержимое, затем сохраните или восстановите согласованное базовое состояние с помощью подходящего рабочего процесса. Объединяя несвязанные хеши или удаляя Lockfile, чтобы убрать конфликт, вы рискуете скрыть незавершённый перевод.

Настройка провайдера описана в разделах GitHub App, GitHub Actions, GitLab, Bitbucket или Buildkite. Команда check сравнивает настроенные источники с этим Lockfile и сообщает, каких целевых файлов не хватает. Если это не каталоги React .jsonc, команда не проверяет ключи внутри файлов.

Другие данные состояния в домашнем каталоге #

~/.lingo/update-check.json кеширует результаты проверки версий на 24 часа. Учётные данные и анонимный идентификатор телеметрии хранятся отдельно. Ни одно из этих хранилищ не содержит переведённых файлов. Прежде чем удалять данные состояния, определите, какая операция завершилась ошибкой, с помощью раздела Устранение неполадок.