# gt: General Translation CLI tool: JSON
URL: https://generaltranslation.com/en-US/docs/cli/reference/formats/json-files.mdx
---

title: JSON
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.