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 #

json
{
  "$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:

json
{
  "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:

json
{
  "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.

BackendCredential
Lingo.devLINGO_API_KEY
OpenAIOPENAI_API_KEY
AnthropicANTHROPIC_API_KEY
GoogleGOOGLE_API_KEY
MistralMISTRAL_API_KEY
OpenRouterOPENROUTER_API_KEY
Local OllamaNo 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.