Обзор

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

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

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

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

{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  },
  "alerts": {
    "new_lead": "You have a new lead!"
  }
}

{
  "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.

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

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

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

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

Все поля необязательны для каждого ключа. Полное описание и примеры для каждого поля см. в справочнике по метаданным ключей.

Поддержка YAML

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

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