@lingo.dev/cli отправляет исходный контент в движок локализации, ждёт, пока движок подготовит переводы, и записывает результат обратно на диск. Это замена устаревшему сценарию npx lingo.dev — тот же проект, но принципиально другая архитектура.
Что изменилось по сравнению с устаревшим CLI#
Устаревший CLI (npx lingo.dev run) извлекал строки, вызывал LLM напрямую с вашей машины и за один проход записывал файлы локально. Текущий CLI разделяет работу на push и pull:
lingo pushзагружает исходники в ваш движок, запускает серверный процесс и либо ждёт завершения, либо сразу возвращает ID запускаlingo pullзабирает результаты последнего push — работает, даже если вы закрыли терминал во время перевода или выполняете pull с другой машины- lockfile (
.lingo/lock.json) хранит последнюю известную на сервере версию каждой целевой локали, чтобы механизм обнаружения конфликтов мог предупредить о локальных изменениях до того, как они будут перезаписаны
Это открывает две возможности, которых не было в устаревшем CLI: длительные переводы без зависшего терминала и получение результатов на другой машине — не на той, с которой запускался push (или в CI).
Ожидание результатов#
Сейчас lingo push загружает исходники, запускает серверный процесс, ждёт его завершения и записывает результаты — всё одной командой. Передача --wait (-w) явно указывает на это блокирующее поведение. Позже вы также сможете повторно подключиться к завершённому запуску через lingo pull.
lingo push # submit, wait, and write outputs (current default)
lingo push --wait # same thing, made explicit
lingo pull # later: re-attach to the most recent push and download its outputsСкоро изменится: в одном из ближайших релизов поведение по умолчанию станет другим: lingo push будет отправлять запуск и сразу завершаться; для загрузки готовых переводов вы будете использовать lingo pull, а --wait (-w) станет способом снова включить блокирующий сценарий «одна команда».
--wait(-w) блокирует выполнение до завершения процесса и записывает результаты в рамках той же команды.lingo pullповторно подключается к последнему push для этого проекта и загружает его результаты — работает даже после закрытия терминала. Состояние запуска хранится отдельно для каждой машины в~/.lingo/runs/<project-hash>.json, поэтомуpullвозобновляет работу на той же машине.
Авторизация: обе команды читают LINGO_API_KEY (или --api-key, или сессию lingo login). В CI достаточно задать LINGO_API_KEY.
Режимы push#
| Команда | Режим | Когда использовать |
|---|---|---|
lingo push | Инкрементальный — сравнивает исходники с .lingo/lock.json, переводит только новые и изменённые ключи в существующие целевые файлы, остальное сохраняет без изменений | Каждый обычный запуск / CI |
lingo push --backfill-missing | Bootstrap — заполняет целевые ФАЙЛЫ, которых ещё нет | Первый push или после добавления новой локали |
lingo push --force | Полный повторный перевод — перезаписывает все целевые файлы (включая ручные правки); --yes/-y пропускает запрос подтверждения | Редко (например, после изменения глоссария или движка) |
--backfill-missing — это флаг bootstrap. Он выполняет отдельный новый запрос в заданной области и добавляет только целые целевые файлы, которых не хватает, — он НЕ переводит новые ключи в уже переведённых файлах (в отчёте запуска будет указано "already up-to-date", и ключ будет пропущен). Для текущих изменений используйте обычный lingo push.
Редактирование переводов вручную#
Обычный lingo push сохраняет ручные правки на уровне ключей:
- Измените целевую строку (если исходник не менялся) → эта строка сохранится; остальные ключи продолжат обновляться.
- Изменился исходник у отредактированного ключа → для этого ключа будет создан новый перевод, который заменит ручную правку.
- Добавлен новый исходный ключ → он будет переведён и добавлен даже в файлы с ручными правками.
