# gt: General Translation CLI tool: Метаданные по ключам
URL: https://generaltranslation.com/ru/docs/cli/reference/keyed-metadata.mdx
---

title: Метаданные по ключам
description: Добавляйте инструкции по переводу для отдельных ключей в JSON- и YAML-файлы General Translation. Справочник API по метаданным по ключам.

---

Вы предоставляете сопутствующий файл метаданных, который повторяет структуру ключей исходного файла и содержит объект метаданных в каждом конечном узле. Каждый объект содержит инструкции для перевода соответствующего ключа.

CLI автоматически обнаруживает сопутствующие файлы метаданных, проверяет их на соответствие структуре исходного файла и отправляет в систему перевода.

## Поля [#fields]

| Поле                         | Описание                                                             | Тип      | Необязательное | По умолчанию |
| ---------------------------- | -------------------------------------------------------------------- | -------- | -------------- | ------------ |
| [`context`](#context)        | Инструкции по переводу для конкретной строки.                        | `string` | Да             | —            |
| [`maxChars`](#max-chars)     | Максимально допустимое число символов в переведённом тексте.         | `number` | Да             | —            |
| [`sourceCode`](#source-code) | Контекст окружающего исходного кода с ключами в виде путей к файлам. | `object` | Да             | —            |

## Структура файла [#structure]

Сопутствующий файл метаданных должен находиться в том же каталоге, что и исходный файл, соответствовать шаблону имени `{name}.metadata.{ext}` и повторять структуру ключей исходного файла, с объектом метаданных в каждом конечном узле.

```text
translations.json           # исходные строки
translations.metadata.json  # метаданные для каждого ключа
```

Добавляйте записи только для тех ключей, которым нужны специальные указания по переводу.

```json title="translations.json"
{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  }
}
```

```json title="translations.metadata.json"
{
  "nav": {
    "bank": {
      "context": "Речной берег — сторона реки. НЕ финансовое учреждение."
    },
    "save": {
      "context": "Спортивный термин — вратарь, отражающий удар. НЕ сохранение данных.",
      "maxChars": 12
    }
  }
}
```

## `context` [#context]

**Тип** `string` · **Необязательно** · **По умолчанию** —

Инструкции по переводу для конкретной строки. Используйте это поле, чтобы снять неоднозначность у слов с несколькими значениями, указать терминологию предметной области или уточнить подразумеваемый смысл.

```json
{
  "bank": {
    "context": "Riverbank. The side of a river where land meets water, NOT a financial institution."
  }
}
```

## `maxChars` [#max-chars]

**Тип** `number` · **Необязательно** · **По умолчанию** —

Максимальное ограничение по числу символов в переводе. Механизм будет использовать более короткие синонимы, сокращения или лаконичные формулировки, чтобы уложиться в это ограничение. Это работает по возможности: если уложиться в ограничение для исходного текста невозможно, возвращается полный перевод.

```json
{
  "save": {
    "maxChars": 10
  }
}
```

## `sourceCode` [#source-code]

**Тип** `object` · **Необязательно** · **По умолчанию** —

Контекст исходного кода вокруг строки. Ключом служит путь к файлу, а каждая запись содержит `before` (строки исходного кода над целевой строкой), `target` (строка, содержащая переводимую строку) и `after` (строки исходного кода под целевой строкой). Если одна и та же строка встречается в разных местах, для одного файла поддерживается несколько записей.

```json
{
  "new_lead": {
    "sourceCode": {
      "components/Dashboard.tsx": [
        {
          "before": "function NotificationBanner({ type }) {\n  const gt = useGT();",
          "target": "  const msg = gt('You have a new lead!');",
          "after": "  return <Banner variant=\"success\">{msg}</Banner>;\n}"
        }
      ]
    }
  }
}
```

### Комбинированный пример

Все три поля в одном ключе:

```json
{
  "save_button": {
    "context": "Sports term. A goalkeeper's save — preventing a goal from being scored. NOT saving data.",
    "maxChars": 12,
    "sourceCode": {
      "components/MatchStats.tsx": [
        {
          "before": "const stats = useMatchStats();\nconst gt = useGT();",
          "target": "const label = gt('Save');",
          "after": "return <StatBadge icon={<GoalkeeperIcon />}>{label}: {stats.saves}</StatBadge>;"
        }
      ]
    }
  }
}
```

## YAML [#yaml]

Метаданные работают аналогично с сопутствующими файлами `.metadata.yaml` или `.metadata.yml`.

```yaml title="translations.metadata.yaml"
ui:
  buttons:
    save:
      context: "Sports term. A goalkeeper's save, NOT saving data."
      maxChars: 12
  labels:
    date:
      context: "The edible fruit of the date palm. NOT a calendar date."
```

## Проверка [#validation]

CLI проверяет файл метаданных на соответствие исходной структуре и завершает работу с ошибкой, если ключ метаданных отсутствует в исходнике, тип значения не соответствует исходнику (примитив или объект, массив или объект), не совпадает корневой тип или файл не удаётся разобрать.

## Схема и сопоставление [#schema]

Метаданные по ключам работают со схемами JSON (`include` и `composite`) и YAML (`include`); метаданные преобразуются через тот же pipeline схем, чтобы пути ключей совпадали во время перевода. Сопутствующие файлы сопоставляются со своим исходным файлом и сами по себе не переводятся — файл `.metadata.json` без соответствующего исходного файла рассматривается как обычный файл. Изменение только метаданных не запускает повторный перевод; должно измениться и исходное содержимое.