Alpha
The Lingo.dev Compiler is in alpha. It is unstable, not recommended for production use, and APIs may change between releases.
The Lingo.dev Compiler operates in two build modes that control whether new translations are generated during the build. Understanding these modes is essential for setting up a reliable development, CI, and production pipeline.
The two modes#
| Mode | Behavior | When to use |
|---|---|---|
"translate" | Generates missing translations by calling the configured LLM provider. Cached translations are reused. | Development and CI - when new or changed text needs translation. |
"cache-only" | Uses only translations from .lingo/metadata.json. Fails if any translation is missing. | Production builds - deterministic output with no external API calls. |
How translate mode works#
In translate mode, the compiler checks each translatable string against .lingo/metadata.json. If a cached translation exists and the source text has not changed, the cached version is used. If the string is new or modified, the compiler calls the configured translation provider to generate a translation and updates the cache.
{
buildMode: "translate",
}This mode is the default. It works with both the pseudotranslator (for instant fake translations) and real LLM providers.
How cache-only mode works#
In cache-only mode, the compiler reads translations exclusively from .lingo/metadata.json. No LLM calls are made. If any translatable string is missing from the cache, the build fails with an error listing the missing strings.
.lingo/metadata.json must be committed to version control. Production builds in cache-only mode depend on this file being present in the repository - not just generated locally.
{
buildMode: "cache-only",
}This mode produces deterministic builds - the same source code and cache always produce the same output. It also eliminates external API dependencies during production builds.
Recommended workflow#
Development - pseudotranslator
Enable the pseudotranslator for instant feedback with no API calls:
{
buildMode: "translate",
dev: {
usePseudotranslator: true,
},
}Pseudotranslations appear as [!!! Welcome !!!], making it easy to spot untranslated strings and test layout with varying text lengths.
CI - translate mode
Run with buildMode: "translate" and a real LLM provider. The CI job generates translations for any new or changed strings and commits the updated .lingo/metadata.json back to the repository.
# CI environment
LINGO_BUILD_MODE=translate npm run buildProduction - cache-only mode
Deploy with buildMode: "cache-only" to use only pre-generated translations. No API keys are needed in the production environment.
# Production environment
LINGO_BUILD_MODE=cache-only npm run buildEnvironment variable override#
The LINGO_BUILD_MODE environment variable overrides the buildMode config option. This lets you use the same config file across environments:
# Override in any environment
LINGO_BUILD_MODE=cache-only npm run buildThe environment variable takes precedence over the config file value.
CI examples#
# .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"Always commit .lingo/metadata.json to version control. Production builds in cache-only mode depend on this file. If it is missing or incomplete, the build will fail.