CLI v0 configuration
Configure legacy buckets, locale paths, and translation backends without mixing generations.
lingo.dev@0.138.10 reads i18n.json from the working directory. A bucket names its parser and discovers files; locale settings identify the source and targets. This is a separate contract from current .lingo/config.json.
Declare locales and buckets #
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": { "source": "en", "targets": ["es", "fr"] },
"buckets": {
"json": {
"include": ["locales/[locale].json"],
"lockedKeys": ["brand/name"],
"ignoredKeys": ["internal/*"],
"preservedKeys": ["legal/terms"]
},
"markdown": {
"include": ["docs/[locale]/*.md"],
"exclude": ["docs/[locale]/drafts/*.md"]
}
}
}Paths resolve relative to configuration. The bucket key selects the parser, not the file extension. Check the legacy format/output matrix when a format stores several locales in one file.
The version field records the schema generation. A legacy schema migration can update that file without migrating to the current CLI. Preserve the previous config and inspect any generated change.
Match paths deliberately #
[locale] expands to the source or target code. A path-specific delimiter supports underscore filenames:
{
"include": [
"standard/[locale].json",
{ "path": "legacy/[locale].json", "delimiter": "_" }
]
}For en-US, the second path uses legacy/en_US.json. Filename representation is separate from normalized locale values sent to the backend.
Recursive ** discovery is available from 0.135.0; older releases need explicit paths. Recursive defaults exclude node_modules, .git, dist, build, .next, and .turbo. Add exclusions for other generated trees.
Assign key behavior #
Legacy key controls use slash-separated traversal and wildcard matching. modules/ai.translation selects the literal dotted key inside modules. Locking copies source values, ignoring omits output, and preservation seeds missing values from source before leaving them human-owned. injectLocale selects output keys for the target locale code.
Use Key controls for exact consequences. A translation instruction is not structural protection, and a source-language placeholder still needs human translation before use.
Choose a localization engine or direct provider #
With a Lingo.dev credential, engineId selects a localization engine's glossary, rules, voice, and models. Prefer explicit selection. Omission uses backend policy rather than naming a stable configuration; the current service can require an ID or select the oldest enabled localization engine accessible to the key.
Direct providers use a provider ID, model, and prompt. This historical shape is not a recommendation that the named model remains available:
{
"provider": {
"id": "openai",
"model": "gpt-4o-mini",
"prompt": "Translate the provided text from {source} to {target}."
}
}The prompt substitutes locale codes for {source} and {target}. Do not rely on provider.baseUrl to redirect lingo.dev@0.138.10's run requests. Its OpenAI path passes baseUrl, while the pinned provider dependency reads baseURL, so that configuration value is ignored. The dependency supports OPENAI_BASE_URL instead; verify the intended destination before sending content or credentials. The Ollama path also ignores provider.baseUrl and creates the provider with defaults. Its service must be reachable from the runner; a remote runner cannot use a laptop's localhost address.
| Backend | Credential |
|---|---|
| Lingo.dev | LINGO_API_KEY |
| OpenAI | OPENAI_API_KEY |
| Anthropic | ANTHROPIC_API_KEY |
GOOGLE_API_KEY | |
| Mistral | MISTRAL_API_KEY |
| OpenRouter | OPENROUTER_API_KEY |
| Local Ollama | No provider API key in the local setup. |
LINGO_API_URL changes the Lingo.dev service destination; compatibility and trust still need checking. Keep credentials out of config and logs. After changing backend or discovery, reproduce a small first-file run. Changing a model or prompt does not change source fingerprints, so existing text needs deliberate refresh when that is the intention.