# gt: General Translation CLI tool: Метаданные для ключей URL: https://generaltranslation.com/ru/docs/cli/reference/keyed-metadata.mdx --- title: Метаданные для ключей description: Метаданные перевода для отдельных ключей в файлах JSON и YAML --- ## Обзор Метаданные для ключей позволяют добавлять инструкции по переводу для отдельных ключей в JSON- и YAML-файлах. Для этого рядом с исходным файлом нужно указать файл `.metadata.json` или `.metadata.yaml`, который повторяет структуру его ключей и содержит объекты метаданных на уровне конечных узлов. CLI автоматически обнаруживает сопутствующие файлы метаданных, проверяет их на соответствие структуре исходного файла и отправляет в движок перевода. *** ## Структура файла Сопутствующий файл метаданных должен: * Находиться в том же каталоге, что и исходный файл * Соответствовать шаблону имени `{name}.metadata.{ext}` (например, `translations.metadata.json` для `translations.json`) * Повторять структуру ключей исходного файла ``` translations.json # исходные строки translations.metadata.json # метаданные для каждого ключа ``` Файл метаданных повторяет структуру исходных ключей, но вместо строк в конечных узлах используются объекты метаданных: ```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": { "bank": { "context": "Речной берег — сторона реки. НЕ финансовое учреждение." }, "save": { "context": "Спортивный термин — вратарь, отражающий удар. НЕ сохранение данных.", "maxChars": 12 } }, "alerts": { "new_lead": { "context": "Контекст продаж/CRM. «Лид» — потенциальный клиент.", "maxChars": 30 } } } ``` Метаданные нужны не для каждого ключа — для `home` выше записи нет, и он переводится как обычно. Добавляйте записи только для тех ключей, которым нужны специальные указания по переводу. *** ## Справка по полям | Поле | Тип | Обязательно | Описание | | ------------ | --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------- | | `context` | `string` | Нет | Инструкции по переводу для этой конкретной строки | | `maxChars` | `number` | Нет | Максимальное количество символов в переведённом тексте | | `sourceCode` | `Record` | Нет | Контекст окружающего исходного кода, где ключами служат пути к файлам | *** ## Поля ### `context` Тип: `string` Инструкции по переводу для конкретной строки. Используйте это поле, чтобы снять неоднозначность у слов с несколькими значениями, указать терминологию предметной области или уточнить подразумеваемый смысл. ```json { "bank": { "context": "Riverbank. The side of a river where land meets water, NOT a financial institution." } } ``` ### `maxChars` Тип: `number` Максимальное ограничение по числу символов в переводе. Механизм будет использовать более короткие синонимы, сокращения или лаконичные формулировки, чтобы уложиться в это ограничение. Это работает по возможности. Если уложиться в ограничение для исходного текста невозможно, возвращается полный перевод. ```json { "save": { "maxChars": 10 } } ``` ### `sourceCode` Тип: `Record` Контекст исходного кода вокруг строки. Ключом служит путь к файлу, а каждая запись содержит: * `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 {msg};\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 }>{label}: {stats.saves};" } ] } } } ``` *** ## 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 draft: context: "Beer on tap, as in 'draft beer'. NOT a document version." labels: date: context: "The edible fruit of the date palm. NOT a calendar date." ``` *** ## Валидация CLI проверяет, соответствует ли файл метаданных структуре исходного файла. Процесс завершается с ошибкой, если: * Ключ из метаданных отсутствует в исходном файле * Значение метаданных является примитивом там, где в исходном файле находится вложенный объект * Значение метаданных является массивом там, где в исходном файле находится объект (или наоборот) * Корневой тип (массив или объект) не совпадает с исходным файлом * Файл метаданных не удаётся распарсить *** ## Поддержка схем Метаданные для ключей работают со схемами JSON (`include` и `composite`) и YAML (`include`). Метаданные автоматически преобразуются в том же конвейере обработки схем, что и исходное содержимое, поэтому пути к ключам при переводе совпадают независимо от структуры файла. *** ## Фильтрация сопутствующих файлов Сопутствующие файлы метаданных автоматически сопоставляются с соответствующим исходным файлом. Они не переводятся как автономные файлы. Это правило действует только если соответствующий исходный файл есть в списке файлов. Файл `.metadata.json` без соответствующего исходного файла обрабатывается как обычный файл. *** ## Поведение при повторном переводе Изменения только в файле метаданных не запускают повторный перевод, если исходное содержимое не менялось. Чтобы применить обновлённые метаданные, необходимо изменить и исходное содержимое.