The CLI translates six file formats. The format is inferred from the file extension; set format on a files[] entry to override it.
| Format | Extensions | format value | Notes |
|---|---|---|---|
| JSON | .json | json | Key/value. Supports key controls. |
| JSONC | .jsonc | jsonc | JSON with comments. Comments survive and double as translator notes. |
| Markdown | .md | md | Prose translated; frontmatter opt-in. |
| MDX | .mdx | mdx | Markdown + JSX. Component props opt-in. |
| Markdoc | .mdoc | markdoc | Markdown + tags. Frontmatter + tag attributes. |
| OpenAPI YAML | .yaml | yaml-openapi | OpenAPI specs. Always set format explicitly. |
See it end to end
The demo project ships one file per format with the exact config each needs. Clone it with npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo and run a push.
npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo
cd my-lingo-demoJSON and JSONC#
Plain key/value translation. Every string value is translated unless a key control says otherwise.
{ "pattern": "content/en/app.json", "lockedKeys": ["meta.version"] }JSONC additionally preserves comments, which the engine reads as context — see translator notes.
{ "pattern": "content/en/settings.jsonc", "preservedKeys": ["featureFlags"] }Markdown, MDX, and Markdoc#
Body prose is translated by default. Frontmatter and embedded components are not translated unless you opt in.
Frontmatter#
List the frontmatter fields to translate with translateFrontmatterFields:
{
"pattern": "content/en/guide.md",
"translateFrontmatterFields": ["title", "description"]
}MDX component props#
For MDX, translate specific props on specific components with translateComponentProps:
{
"pattern": "content/en/landing.mdx",
"translateFrontmatterFields": ["title"],
"translateComponentProps": [{ "component": ["Hero", "Callout"], "props": ["title", "body"] }]
}This translates the title and body props on <Hero> and <Callout> and leaves all other props untouched.
Markdoc#
Markdoc works like Markdown, with frontmatter and tag attributes preserved:
{
"pattern": "content/en/changelog.mdoc",
"translateFrontmatterFields": ["title"]
}OpenAPI YAML#
Generic YAML is ambiguous, so OpenAPI specs require an explicit format:
{ "pattern": "content/en/api.yaml", "format": "yaml-openapi" }The engine translates human-facing fields (summaries, descriptions) and leaves schema keys, paths, and operation IDs intact.
Output paths#
Targets are written by substituting the locale segment of the source pattern — content/en/app.json → content/de/app.json. Keep the source locale in the path so the CLI knows where targets go. See Configuration.
Coming from the legacy CLI?#
The legacy CLI supported ~25 formats (CSV, PO, XLIFF, Android/Xcode strings, Flutter ARB, HTML, and more). Support for those is being added to the current CLI by usage; until your format lands, the legacy CLI docs cover it.
