# General Translation Changelog: gtx-cli 2.10.0: Инструкции по переводу для каждого ключа
URL: https://generaltranslation.com/ru/blog/gtx-cli_v2_10_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 
Authors: Fernando Aviles
Published: 2026-03-12

## Обзор

**gtx-cli 2.10.0** добавляет поддержку **метаданных на уровне ключей** в файлах перевода JSON и YAML. Это инструкции по переводу для отдельных ключей, которые дают вам более точный контроль над переводом отдельных строк.

До сих пор контекст перевода для файлов с ключами задавался на уровне проекта. Настройки стиля, записи глоссария и правила для конкретных локалей применялись ко всему контенту сразу. Метаданные на уровне ключей позволяют пойти ещё глубже и добавлять конкретные подсказки по переводу непосредственно к отдельным ключам в ваших файлах.

***

## Как это выглядит

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

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

```json title="translations.metadata.json"
{
  "nav": {
    "home": {
      "context": "Бейсбольный термин — домашняя база на поле. НЕ дом."
    },
    "bank": {
      "context": "Берег реки — сторона реки. НЕ финансовое учреждение."
    },
    "save": {
      "context": "Спортивный термин — вратарь, отражающий удар. НЕ сохранение данных.",
      "maxChars": 12
    }
  },
  "alerts": {
    "new_lead": {
      "context": "Контекст продаж/CRM. «Лид» — потенциальный клиент.",
      "maxChars": 30
    }
  }
}
```

Сопутствующий файл должен находиться в том же каталоге, что и исходный файл, и иметь имя по шаблону `{name}.metadata.json` (или `.metadata.yaml` для YAML-файлов). CLI автоматически подхватывает его при запуске [`npx gt translate`](/docs/cli/reference/commands/translate).

Если задать контекст для каждого ключа, "Bank" будет переводиться как "Ribera" (речной берег), а не как возможное "Banco" (финансовое учреждение), а "Save" — как "Parada" (сейв вратаря), а не "Guardar" (сохранить). Для строк, которые и так однозначны, метаданные вообще не нужны — добавляйте записи только для тех ключей, которым это действительно полезно.

***

## Поддерживаемые поля

Сейчас поддерживаются три поля метаданных:

* **`context`** — инструкции по переводу конкретной строки. Это самое важное поле: используйте его, чтобы снять неоднозначность, указать терминологию предметной области или уточнить смысл.
* **`maxChars`** — максимально допустимое число символов в переводе. Это ограничение соблюдается по возможности: движок будет использовать более короткие синонимы и лаконичные формулировки, чтобы уложиться в лимит, но не станет обрезать перевод до нереалистично короткой длины.
* **`sourceCode`** — окружающий строку фрагмент исходного кода. Позволяет показать движку, где и как эта строка используется в вашей кодовой базе, что помогает ему точнее подбирать тон, терминологию и формулировки.

Все поля необязательны для каждого ключа. Полное описание и примеры для каждого поля см. в [справочнике по метаданным ключей](/docs/cli/reference/keyed-metadata).

***

## Поддержка YAML

Тот же подход применим и к YAML-файлам. Создайте сопутствующий файл `.metadata.yaml` с той же структурой ключей:

```yaml title="translations.metadata.yaml"
ui:
  buttons:
    save:
      context: "Спортивный термин — сейв вратаря. НЕ сохранение данных."
    draft:
      context: "Разливное пиво (как в выражении 'draft beer'). НЕ версия документа."
  labels:
    date:
      context: "Съедобный плод финиковой пальмы. НЕ календарная дата."
    chips:
      context: "Британский английский: горячие жареные полоски картофеля (картофель фри). НЕ чипсы и не микросхемы."
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.