<!-- LLM_VERSION_INFO
FORMAT: text/markdown
CONTENT_TYPE: article
ORIGINAL_URL: https://lingo.dev/en/cli/formats/csv-per-locale
ALTERNATE_VERSION: en/cli/formats/csv-per-locale/index.html (text/html)
EXTRACTION_DATE: 2026-04-18T22:19:35.046Z

This is the markdown version with text-only content (images converted to alt-text).
For rich formatting with images, request the HTML version at: en/cli/formats/csv-per-locale/index.html
-->

# 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`](/content/en/docs/cli/configuration/index.html) to define which files the CLI should translate.

## [Bucket types](/content/en/docs/cli/supported-formats#bucket-types/index.html)

| 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](/content/en/docs/cli/supported-formats#output-modes/index.html)

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:

```json
{
  "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:

```json
{
  "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](/content/en/docs/cli/supported-formats#configuration-examples/index.html)

### [Web app with JSON](/content/en/docs/cli/supported-formats#web-app-with-json/index.html)

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

### [Documentation site with Markdown](/content/en/docs/cli/supported-formats#documentation-site-with-markdown/index.html)

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

### [Mobile app (iOS + Android)](/content/en/docs/cli/supported-formats#mobile-app-(ios-+-android/index.html))

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

### [Monorepo with multiple formats](/content/en/docs/cli/supported-formats#monorepo-with-multiple-formats/index.html)

```json
{
  "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](/content/en/docs/cli/supported-formats#bucket-specific-features/index.html)

Some buckets support additional features beyond include/exclude patterns:

| Feature                    | Supported buckets                      | Description                                     |
|----------------------------|----------------------------------------|-------------------------------------------------|
| [Key Locking](/content/en/docs/cli/key-locking/index.html)             | Key-value formats (JSON, YAML, etc.)    | Copy source values without translation          |
| [Key Ignoring](/content/en/docs/cli/key-ignoring/index.html)            | Key-value formats                          | Exclude keys from target files entirely          |
| [Key Preserving](/content/en/docs/cli/key-preserving/index.html)        | Key-value formats                          | Initialize once, then protect from updates      |
| [Translator Notes](/content/en/docs/cli/translator-notes/index.html)    | JSONC, XCStrings                          | Provide context via comments to improve translation|

## [Include pattern rules](/content/en/docs/cli/supported-formats#include-pattern-rules/index.html)

- 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](/content/en/docs/cli/supported-formats#next-steps/index.html)

[i18n.json  
 Full configuration reference](/content/en/docs/cli/configuration/index.html) [Key Locking  
 Protect specific keys from translation](/content/en/docs/cli/key-locking/index.html) [Existing Translations  
 Add the CLI to a project that already has translations](/content/en/docs/cli/existing-translations/index.html) [Setup  
 Install and configure the CLI](/content/en/docs/cli/setup/index.html)