Режимы сборки
Альфа
Lingo.dev Compiler находится в альфа-версии. Он нестабилен, не рекомендуется для использования в production, а API могут меняться от релиза к релизу.
Lingo.dev Compiler работает в двух режимах сборки, которые определяют, будут ли новые переводы генерироваться во время сборки. Понимание этих режимов важно для настройки надёжного пайплайна разработки, CI и production.
Два режима#
| Режим | Поведение | Когда использовать |
|---|---|---|
"translate" | Генерирует недостающие переводы через настроенного LLM-провайдера. Кэшированные переводы используются повторно. | Разработка и CI — когда новым или изменённым текстам нужен перевод. |
"cache-only" | Использует только переводы из .lingo/metadata.json. Если хотя бы один перевод отсутствует, сборка завершается ошибкой. | Production-сборки — детерминированный результат без внешних вызовов API. |
Как работает режим translate#
В режиме translate Compiler проверяет каждую переводимую строку по .lingo/metadata.json. Если кэшированный перевод уже есть и исходный текст не изменился, используется версия из кэша. Если строка новая или была изменена, Compiler обращается к настроенному провайдеру перевода, генерирует перевод и обновляет кэш.
{
buildMode: "translate",
}Это режим по умолчанию. Он работает как с pseudotranslator для мгновенных тестовых переводов, так и с реальными LLM-провайдерами.
Как работает режим cache-only#
В режиме cache-only Compiler читает переводы только из .lingo/metadata.json. Вызовы LLM не выполняются. Если в кэше отсутствует хотя бы одна переводимая строка, сборка завершается ошибкой со списком недостающих строк.
.lingo/metadata.json должен быть закоммичен в систему контроля версий. Production-сборки в режиме cache-only зависят от наличия этого файла в репозитории, а не только от его локальной генерации.
{
buildMode: "cache-only",
}Этот режим обеспечивает детерминированные сборки: один и тот же исходный код и кэш всегда дают одинаковый результат. Он также устраняет зависимость от внешних API во время production-сборок.
Рекомендуемый Процесс#
Разработка — pseudotranslator
Включите pseudotranslator, чтобы мгновенно получать результат без вызовов API:
{
buildMode: "translate",
dev: {
usePseudotranslator: true,
},
}Псевдопереводы отображаются как [!!! Welcome !!!], поэтому непереведённые строки легко заметить, а интерфейс удобно тестировать с разной длиной текста.
CI — режим translate
Запускайте с buildMode: "translate" и реальным LLM-провайдером. CI-задача генерирует переводы для всех новых или изменённых строк и коммитит обновлённый .lingo/metadata.json обратно в репозиторий.
# CI environment
LINGO_BUILD_MODE=translate npm run buildProduction — режим cache-only
Развёртывайте с buildMode: "cache-only", чтобы использовать только заранее сгенерированные переводы. В production-окружении ключи API не понадобятся.
# Production environment
LINGO_BUILD_MODE=cache-only npm run buildПереопределение через переменную окружения#
Переменная окружения LINGO_BUILD_MODE переопределяет опцию конфигурации buildMode. Это позволяет использовать один и тот же конфигурационный файл в разных окружениях:
# Override in any environment
LINGO_BUILD_MODE=cache-only npm run buildПеременная окружения имеет приоритет над значением в конфигурационном файле.
Примеры для CI#
# .github/workflows/translate.yml
name: Generate Translations
on:
push:
branches: [main]
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
env:
LINGO_BUILD_MODE: translate
LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
- uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: "chore: update translations"
file_pattern: ".lingo/metadata.json"Всегда коммитьте .lingo/metadata.json в систему контроля версий. Production-сборки в режиме cache-only зависят от этого файла. Если он отсутствует или неполный, сборка завершится ошибкой.