# gt: General Translation CLI tool: YAML
URL: https://generaltranslation.com/en-GB/docs/cli/reference/formats/yaml-files.mdx
---

title: YAML
description: Translate YAML files with the General Translation CLI. API reference for the YAML file format.

---

The CLI translates YAML files regardless of which i18n library you use. Both `.yaml` and `.yml` extensions are supported, and 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 strings with custom syntax less accurately.*

## Configuration [#config]

Add a `yaml` 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": {
    "yaml": {
      "include": ["i18n/[locale]/*.yaml"]
    }
  }
}
```

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.yaml` file that mirrors your source structure.

```yaml title="translations.metadata.yaml"
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.