Supported Formats

Max Prilutskiy · Updated about 1 month ago · 4 min read

The Lingo.dev CLI uses bucket types to parse and translate different file formats. Each bucket type is a dedicated parser designed for a specific format. Configure one or more buckets in your i18n.json to define which files the CLI should translate.

Bucket types

Bucket type Format Output mode [locale] required
json JSON files Separate files per locale Yes
json5 JSON5 files Separate files per locale Yes
jsonc JSONC files (with comments) Separate files per locale Yes
json-dictionary JSON dictionary (flat key-value) Separate files per locale Yes
yaml YAML files Separate files per locale Yes
yaml-root-key YAML with locale root keys Mutates source file No
markdown Markdown files Separate files per locale Yes
mdx MDX files Separate files per locale Yes
markdoc Markdoc files Separate files per locale Yes
html HTML files Separate files per locale Yes
mjml MJML email templates Separate files per locale Yes
android Android XML resources Separate files per locale Yes
xcode-strings Xcode .strings files Separate files per locale Yes
xcode-stringsdict Xcode .stringsdict files Separate files per locale Yes
xcode-xcstrings Xcode .xcstrings catalogs Mutates source file No
flutter Flutter ARB files Separate files per locale Yes
po GNU gettext PO files Separate files per locale Yes
properties Java .properties files Separate files per locale Yes
csv CSV files Mutates source file No
csv-per-locale CSV files (one per locale) Separate files per locale Yes
xml Generic XML files Separate files per locale Yes
xliff XLIFF files Separate files per locale Yes
srt SRT subtitle files Separate files per locale Yes
vtt VTT subtitle files Separate files per locale Yes
php PHP localization arrays Separate files per locale Yes
typescript TypeScript files Separate files per locale Yes
vue-json Vue i18n JSON blocks Separate files per locale Yes
txt Plain text files Separate files per locale Yes

Output modes

Buckets operate in one of two output modes:

Separate files per locale

  • the CLI creates a distinct file for each target language. Include patterns must contain the [locale] placeholder:
{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

This produces locales/en.json, locales/es.json, locales/fr.json, etc.

Mutates source file

  • the CLI writes translations back into the same file that contains the source content. The [locale] placeholder is not used:
{
  "buckets": {
    "csv": {
      "include": ["translations.csv"]
    }
  }
}

CSV files typically store all locales in columns within a single file. Xcode .xcstrings catalogs and YAML with root keys work similarly.

Configuration examples

Web app with JSON

{
  "buckets": {
    "json": {
      "include": ["src/locales/[locale].json"],
      "lockedKeys": ["brand/name"]
    }
  }
}

Documentation site with Markdown

{
  "buckets": {
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

Mobile app (iOS + Android)

{
  "buckets": {
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/app/src/main/res/values-[locale]/strings.xml"]
    }
  }
}

Monorepo with multiple formats

{
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "flutter": {
      "include": ["apps/mobile/lib/l10n/app_[locale].arb"]
    }
  }
}

Bucket-specific features

Some buckets support additional features beyond include/exclude patterns:

Feature Supported buckets Description
Key Locking Key-value formats (JSON, YAML, etc.) Copy source values without translation
Key Ignoring Key-value formats Exclude keys from target files entirely
Key Preserving Key-value formats Initialize once, then protect from updates
Translator Notes JSONC, XCStrings Provide context via comments to improve translation

Include pattern rules

  • Patterns are relative to the i18n.json file location
  • Use [locale] as the placeholder for locale codes (required for "separate files" buckets)
  • Asterisk (*) matches any filename: locales/[locale]/*.json
  • Recursive patterns (**/*.json) are not supported
  • File extensions do not affect parsing - the bucket type determines the parser.

Next Steps

i18n.json
Full configuration reference Key Locking
Protect specific keys from translation Existing Translations
Add the CLI to a project that already has translations Setup
Install and configure the CLI