# 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: The CLI reads `package.json` to decide how JSON strings are handled. `next-intl` uses ICU messages, and so does `i18next` when `i18next-icu` is installed. `i18next` alone keeps i18next syntax such as `{{name}}` interpolation. Other libraries are translated as plain strings, so custom syntax may be less accurate.*

## 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.

## Output order [#order]

The CLI does not sort keys in translated JSON files. GTJSON translation files configured with [`files.gt`](/docs/cli/reference/config#files) remain sorted by key for stable diffs.

<Callout type="info">
  **Changed in v2.26.0:** Translated JSON files are no longer sorted alphabetically. GTJSON output remains sorted.
</Callout>

## 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.
