Supported Formats

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#

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:

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#