# gt: General Translation CLI tool: YAML
URL: https://generaltranslation.com/en-US/docs/cli/formats/yaml.mdx
---
title: YAML
description: How to automatically translate YAML files with General Translation
---

## Overview

`gt` can be used to automatically translate your project's YAML files, regardless of what i18n library you are using.

<Callout type='info'>
  **Note:** We currently support custom string syntax and formatting for the
  following 3rd-party i18n libraries: `next-intl`, `i18next`. If you are using a
  different i18n library, the translation results may not be accurate for
  strings with custom syntax and formatting (for example, ICU messages). Don't
  see your favorite library? [Please let us
  know](https://github.com/generaltranslation/gt/issues), and we will add it as
  soon as we can!
</Callout>

We will follow these 4 steps:

<Steps>
  <Step>
    Add your environment variables
  </Step>
  <Step>
    Install [`gt`](/docs/cli)
  </Step>
  <Step>
    Create a `gt.config.json` file
  </Step>
  <Step>
    Run [`gt translate`](/docs/cli/translate#translate)
  </Step>
</Steps>

---

## Step 1: Add your environment variables

Add your production API key and project ID to your environment variables.
This is necessary to use the `gt` tool.
You get these from the [General Translation dashboard](https://generaltranslation.com/dashboard).

```bash title=".env"
GT_API_KEY=<your-api-key>
GT_PROJECT_ID=<your-project-id>
```

## Step 2: Install `gt`

Install the `gt` tool in your project.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
  ```bash
  npm i gt
  ```
  </Tab>
  <Tab value="yarn">
  ```bash
  yarn add --dev gt
  ```
  </Tab>
  <Tab value="bun">
  ```bash
  bun add --dev gt
  ```
  </Tab>
  <Tab value="pnpm">
  ```bash
  pnpm add --save-dev gt
  ```
  </Tab>
</Tabs>

## Step 3: Create a `gt.config.json` file

Create a `gt.config.json` file in the root of your project.

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

Feel free to customize the `gt.config.json` file to your needs. See the [configuration](/docs/cli/reference/config) docs for more information.

Update the `yaml` file format such that the `include` path matches your project structure. Both `.yaml` and `.yml` extensions are supported.

<Callout>Translations will preserve the original string syntax.</Callout>

## Step 4: Add the `gt translate` command to your build process

Add the `gt translate` command to your build or CI process before the build command to automatically add translations to your project.

```json title="package.json"
{
  "scripts": {
    "translate": "npx gt translate",
    "build": "npm run translate && <your build command>"
  }
}
```

This will generate translations for all of your locales and save them to your project.
If you want to commit these files to your repo, you can instead run this command before committing.

You're done! Now your project will automatically update all of your translation YAML files any time your project changes.

---

## Keyed metadata

You can attach per-key translation instructions to individual strings using a companion `.metadata.yaml` file. This lets you provide context, character limits, and source code context for specific keys without modifying the source file.

```yaml title="translations.yaml"
nav:
  home: "Home"
  bank: "Bank"
  save: "Save"
alerts:
  new_lead: "You have a new lead!"
```

```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
alerts:
  new_lead:
    context: "Sales/CRM context. A 'lead' is a potential customer."
    maxChars: 30
```

Not every key needs metadata — only provide entries for keys that need specific translation instructions.

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

---

## Notes

- You can automatically add translations to your project with the [`gt translate`](/docs/cli/translate#translate) command.
- If you want to commit your translation files, you should run the `gt translate` command before committing.
- To configure the output path for your translations, see the [configuration](/docs/cli/reference/config) docs.
- Both `.yaml` and `.yml` extensions are supported.

## Next steps

- See the [usage guide](/docs/cli/reference/usage) for the CLI tool.
- Learn about [keyed metadata](/docs/cli/reference/keyed-metadata) for per-key translation instructions.