Static Content Localization

The Lingo.dev CLI translates static files in your repository - Markdown, MDX, Markdoc, JSON, YAML, subtitles, and more - through a configured localization engine. Point it at your content, run once, and get translated files alongside your source.

Supported Content Types#

Prerequisites#

Every CLI run sends content through a localization engine - the configuration that determines which LLM model, glossary, brand voice, and instructions apply. Create one in the Lingo.dev dashboard and generate an API key.

Documentation Sites#

Most documentation frameworks organize translated content in per-locale directories. The CLI's markdown, mdx, and markdoc buckets translate these files while preserving frontmatter, code blocks, and component syntax.

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "markdown": {
      "include": ["docs/[locale]/getting-started.md"]
    },
    "mdx": {
      "include": ["docs/[locale]/setup.mdx"]
    }
  }
}

Adjust the include pattern to match your framework's directory convention:

Structured Data#

JSON and YAML files translate with the json and yaml buckets. Use locked keys to prevent non-translatable values (IDs, URLs, configuration flags) from being modified.

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["content/[locale].json"],
      "lockedKeys": ["id", "slug", "url"]
    },
    "yaml": {
      "include": ["data/[locale].yaml"]
    }
  }
}

For YAML files that use the locale code as the root key (common in Rails and Hugo), use the yaml-root-key bucket instead - it reads from the source locale key and writes to target locale keys within the same file.

Subtitles#

SRT and VTT subtitle files translate with the srt and vtt buckets. The CLI preserves all timing data, cue indices, and formatting tags - only the text content is translated.

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "srt": {
      "include": ["subs/[locale]/intro.srt"]
    }
  }
}

Working with Large Content#

Static content repositories can contain thousands of files. The CLI handles this efficiently through three mechanisms:

Next Steps#