CLI configuration

Define source discovery, translation options, and target paths in .lingo/config.json.

.lingo/config.json describes the files a project translates and where their targets belong. The CLI searches upward from the working directory for the nearest config and resolves project-relative paths from that root. Local catalog commands use cwd when no config exists.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "locales/en.json" }]
}

Run link to add the organization and localization engine IDs for remote translation. Extraction can use the i18n settings locally without those IDs. Use strict JSON: comments and trailing commas are not accepted here.

Root fields #

FieldMeaning
orgId, engineIdNonempty resource IDs; both form the remote binding.
sourceLocaleNonempty source-locale string.
targetLocalesNonempty-string entries; runtime removes duplicates and the exact source locale.
filesSource entries described below.
i18n.messagesPathExtract/check/clean catalog directory; default locales.
i18n.typesPathExtract/check declaration path; default lingo.d.ts.
github.workflows.onPushToDefaultBranch.enabledOptional default-branch integration trigger.
github.workflows.onPullRequest.enabledOptional pull-request integration trigger.
github.safety.requireApprovalOptional integration run-approval setting.

Unknown root and file-entry keys warn and are ignored. A misspelling can leave a default in effect instead of rejecting the whole file.

Init writes localization settings; link writes binding IDs; unlink removes only those IDs. Writers preserve other root sections, but init --force rebuilds file entries and loses advanced options. GitHub settings neither install the App nor make a CLI push trigger repository automation; use the integration setup.

File-entry fields #

FieldMeaning
patternOne nonempty source pattern.
includeSource patterns; takes precedence over pattern, even when empty.
excludePatterns excluded from this entry.
formatExplicit format from the supported list below.
localeFormatbcp47, underscore, or android path representation.
targetPath, sourceRootOutput template and optional prefix removed for [path].
translateFrontmatterFieldsMetadata fields selected by Markdown-family handlers.
translateComponentPropsProp names or component-filtered prop rules.
lockedKeys, preservedKeys, ignoredKeysNonempty key-path arrays for supporting handlers.
injectLocaleBoolean or { "enabled": true, "key": "language" }.
keyColumnCSV only: key column header; defaults to the first header cell.
lockedPatternsProperties only: RE2 regular expressions kept untranslated in values.

Each entry needs pattern or include; an empty include selects nothing. The first matching entry supplies options. Key controls explains value ownership and format boundaries.

File patterns #

The matcher supports * inside a segment and **/ across directories. Use docs/en/**/* for a recursive subtree; trailing ** alone does not mean the same thing. Do not assume another glob library's brace or extglob behavior.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "files": [
    {
      "include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
      "exclude": ["docs/en/private/**/*"]
    }
  ]
}

An exclusion belongs only to its entry; another entry can still include the file. Discovery skips .git and node_modules, not everything in .gitignore. Positional push patterns further intersect configured sources and change planning mode. Quote them in the shell.

Format selection #

The configured formats are json, jsonc, md, mdx, markdoc, yaml-openapi, po, flutter, xcode-strings, yaml, android, typescript, xcode-xcstrings, srt, xliff, xcode-stringsdict, php, yaml-root-key, html, txt, csv, and properties.

SuffixInferred format
.json, .jsoncJSON or JSONC.
.md, .mdx, .mdocMarkdown, MDX, Markdoc.
.html, .htmHTML.
.po, .arbGettext, Flutter.
.strings, .xcstrings, .stringsdictCorresponding Apple format.
.ts, .mts, .ctsTypeScript.
.srt, .xlf, .xliff, .phpSubRip, XLIFF, PHP.
.txtPlain text, only for a pattern ending in .txt or txt format.
.csvCSV, only for a pattern ending in .csv or csv format.
.propertiesJava properties, only for a pattern ending in .properties or properties format.
.yaml, .ymlSet yaml, yaml-root-key, or yaml-based OpenAPI explicitly.
.xmlSet android explicitly; generic XML is not supported.

For OpenAPI, the exact identifier is yaml-openapi. Explicit format selection still does not bypass discovery's supported suffix list. A .txt, .csv or .properties file belongs only to an entry whose pattern ends in its extension or that sets the matching format, txt, csv or properties, and such an entry selects only files with that extension. .js, .tsx, .pot, MJML, and VTT files are not configured CLI file inputs. React TSX extraction is a different operation.

HTML translation patches selected text and attributes into the original source, preserving untouched markup, comments, and formatting. An explicit <html> element gets the target locale in its lang attribute; fragments stay fragments. See HTML for text selection and output behavior.

Formats describes parser behavior, including skipped shapes and reconstruction limits. Shared server handlers do not expand this CLI enum.

Output paths #

Use an explicit template when source paths do not identify their locale:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    {
      "pattern": "docs/**/*.md",
      "sourceRoot": "docs",
      "targetPath": "i18n/[locale]/docs/[path]"
    }
  ]
}

docs/start.md becomes i18n/de/docs/start.md and i18n/fr/docs/start.md. [locale] uses the entry's locale representation; [path] removes the segment-boundary source root. A root of docs does not remove part of docsite.

Templates require [locale]; glob inputs also require [path]. These are the only placeholders. Absolute paths, .., glob roots, roots outside the inputs, and outputs rediscovered as configured sources are rejected. sourceRoot without targetPath is invalid. Push also checks case-insensitive output collisions.

Push, pull, and purge also follow the filesystem: a source, target, .lingo/lock.json, or .lingo/config.json that resolves outside the project root or into .git, for example through a symbolic link, stops the command with an error before anything is read, written, or deleted there. Links that stay inside the project still work, but a target or lockfile that is itself a link is not written through. In a monorepo, run from a root that contains the shared files rather than linking to them from a package.

Without a template, derivation tries a source-locale directory, whole filename stem, platform layouts, then an inserted locale directory with a warning. Examples include locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → a target .lproj, and Android values → locale-qualified resources. Read warnings and confirm the application loads that destination.

XCStrings and CSV store all locales in the source file and reject targetPath. Several locale outputs intentionally share that file; its existence does not prove each locale is present. Purge skips the shared file, so it cannot remove individual locale entries.

Select metadata and component text #

Markdown-family translation selects title and description frontmatter when the option is omitted. An empty list opts out; an explicit list selects other fields. Nested scalar and array paths need parseable frontmatter; malformed frontmatter can fall back to top-level scanning.

json
{
  "pattern": "docs/en/**/*.mdx",
  "translateFrontmatterFields": ["title", "description"],
  "translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}

A string selects a prop without a component filter. An object selects props and can restrict component names. These rules select literal translatable content, not component code or every attribute. Markdown, MDX, and Markdoc differ; check the handler when switching paths.

For JSONC translator guidance, place @context immediately before its string. General JSONC output keeps @orphan marks but drops other comments, so React's @src metadata needs the catalog loading policy, not an assumption that pull preserves it.

For documentation frameworks, choose actual source/output directories separately from routing. OpenAPI uses yaml-openapi; Rails-style locale roots use yaml-root-key; generic YAML uses yaml. A matching extension alone cannot select the right semantics.

Locales #

Config validates nonempty strings rather than an exhaustive locale enum. Use the identifiers your model and application need, including region or script. localeFormat controls paths: bcp47 retains hyphens, underscore produces pt_BR, and android produces forms such as pt-rBR or b+zh+Hans. Android format selects Android rendering unless overridden; this also affects source matching.

Finish pending ordinary source updates before adding a target and backfilling its missing files. Add a language explains how that order keeps existing languages current. Removing a target stops future selection without deleting existing files. Embedded locale metadata and shared catalogs need their handler's rules. Direction, routing, and language quality are not established by a correctly spelled path.

Catalog paths #

For extraction and checking, explicit --out/--types override i18n settings, then defaults. --source-locale defaults to en independently of localization sourceLocale. Changing messagesPath does not update files[]; select the generated JSONC path for translation.

Monorepos #

A root config can share locales and a localization engine across recursive or explicit package paths. Per-package configs can instead keep locales, configuration, and lockfiles independent. Run from the intended package root so nearest-config discovery does not select an ancestor unexpectedly.

A CI directory matrix should preserve each project's collected output and avoid overlapping writers. Home-local run pointers depend on absolute roots and are not shared by a lockfile. lingo check compares every source selected by files with the lockfile at file level; it does not check keys inside them.

Scoring configuration #

lingo score uses executable lingo.config.ts, loaded through Jiti. It is separate from project JSON and does not register arbitrary local format loaders. Keep trusted scoring plugins and remote file-localization settings distinct.