# gt: General Translation CLI tool: JSON
URL: https://generaltranslation.com/en-US/docs/cli/reference/formats/json-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Translate JSON files with the General Translation CLI. API reference for the JSON file format.

The CLI translates JSON files regardless of which i18n library you use. Translations preserve the original string syntax.

*Note: Custom string syntax and formatting — for example ICU messages — are supported for `next-intl` and `i18next`. Other libraries may translate less accurately for strings with custom syntax.*

## Configuration [#config]

Add a `json` entry under `files` with an `include` array of glob patterns. Use the `[locale]` placeholder so the CLI can find source files and save translations to the right path.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["zh", "es", "ja"],
  "files": {
    "json": {
      "include": ["i18n/[locale]/*.json"],
      "exclude": ["i18n/[locale]/exclude/**/*.json"]
    }
  }
}
```

With this config, the CLI translates every JSON file under `i18n/en/`, saves the results to `i18n/zh/`, `i18n/es/`, and `i18n/ja/`, and skips files under `i18n/en/exclude/`. See the [configuration reference](/docs/cli/reference/config#files) for all file keys.

## Keyed metadata [#metadata]

Attach per-key translation instructions with a companion `.metadata.json` file that mirrors your source structure. Use it to add context, character limits, or source code context for specific keys without changing the source.

```json title="translations.metadata.json"
{
  "nav": {
    "bank": {
      "context": "Riverbank — the side of a river. NOT a financial institution."
    },
    "save": {
      "context": "Sports term — a goalkeeper preventing a goal. NOT saving data.",
      "maxChars": 12
    }
  }
}
```

See the [keyed metadata reference](/docs/cli/reference/keyed-metadata) for all supported fields.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.