Перевод документов

Загрузите исходные файлы и предыдущие переводы, запустите задание локализации и скачайте готовые файлы.

Задания перевода документов позволяют переводить файлы с сохранением формата. Одно задание может включать несколько файлов и целевых языков. API обращается к каждому файлу по хешу SHA-256, вычисленному по точной последовательности его байтов.

Вам понадобятся ключ API, ИД организации и ИД движка. Полный пример на Node.js вы найдёте в руководстве по локализации файлов.

Выберите формат #

Укажите format.type для каждого документа:

ФорматТип
JSON / JSONCjson / jsonc
Markdown / MDX / Markdocmd / mdx / markdoc
HTMLhtml
TypeScript / PHPtypescript / php
YAML / YAML с локалью в корне / OpenAPI YAMLyaml / yaml-root-key / yaml-openapi
Android / Flutter ARBandroid / flutter
Строки Apple / словари форм множественного числа / каталоги строкxcode-strings / xcode-stringsdict / xcode-xcstrings
Gettext / XLIFF / SubRippo / xliff / srt
Обычный текстtxt
Таблица CSV с отдельным столбцом для каждой локалиcsv
Файлы свойств Javaproperties
Контент Payloadpayload

В справочниках по форматам описаны структуры файлов и параметры управления. В API format.options использует контракт документа. При настройке CLI названия его параметров преобразуются в названия из этого контракта. Например, API использует frontmatterFields для Markdown и componentProps для свойств компонентов. Селекторы ключей JSON используют JSONPath.

Задайте параметры формата #

Вы можете не указывать format.options, чтобы использовать значения по умолчанию. Задавайте только параметры, которые поддерживает выбранный тип:

ТипПараметры
json, jsoncПараметры JSON: правила для ключей, области видимости, контекст, подсказки и вставка локали.
typescript, php, yaml, yaml-root-keylockedKeys, preservedKeys, ignoredKeys (по умолчанию []). Дополнительно — keyScope и termScope, если их значения непустые.
mdfrontmatterFields (по умолчанию ["$.title", "$.description"]). Дополнительно — termScope, если значение непустое.
mdx, markdocПараметры Markdown, а также componentProps (по умолчанию []).
htmlcomponentProps (по умолчанию []) в дополнение к атрибутам, перевод которых уже предусмотрен обработчиком.
xcode-stringsdictlockedKeys и preservedKeys (по умолчанию []). Дополнительно — termScope, если значение непустое.
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapiНеобязательный параметр termScope с непустым значением.
csvНеобязательный параметр keyColumn — заголовок столбца ключей (по умолчанию — первая ячейка строки заголовков).
propertieslockedKeys, preservedKeys, ignoredKeys (по умолчанию []) и необязательное непустое значение keyScope сопоставляются с ключом целиком как шаблоны старого формата или как JSONPath, если шаблон начинается с $. termScope — необязательное непустое значение. lockedPatterns (по умолчанию []) — регулярные выражения RE2, которые не переводятся в значениях.
payload, po, xliff, srt, txtБез дополнительных параметров.

Правила для ключей, области видимости ключей и поля метаданных в начале документа задаются запросами JSONPath. termScope выбирает целиком те единицы исходного текста, которые содержат любой из заданных терминов как подстроку с учётом регистра. "cat" может соответствовать "catalog". Если формат поддерживает и keyScope, и termScope, при указании обоих выбирается их пересечение. Для обеих областей видимости нужны существующие переводы, с которыми будут объединены результаты. Выбор и повторное использование зависят от формата — подробнее в разделе об инкрементальных обновлениях. Эти параметры API отличаются от поддержки форматов --key в CLI.

Правило для свойств компонентов содержит props — непустой массив имён свойств. Вы также можете указать components — непустой массив, который ограничивает действие правила указанными компонентами. Без components правило применяется к любому компоненту. Для MDX:

json
{
  "type": "mdx",
  "options": {
    "frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
    "componentProps": [{ "components": ["Callout"], "props": ["title"] }]
  }
}

Вместе с основным текстом документа будут переведены выбранные метаданные в начале документа и заголовки Callout, заданные строковыми литералами. О защите кода и выражений, а также о восстановлении документа читайте в справочнике по формату.

Создайте задание с адресами артефактов #

Вычислите хеш именно тех байтов, которые собираетесь загрузить. В Node.js:

js
import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";

const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");

Создайте задание, указав полученный адрес в source документа:

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "documents": [
    {
      "key": "messages/en.json",
      "format": { "type": "json" },
      "source": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}

Замените адрес из примера вычисленным хешем. Сохраните полученный ИД задания. В uploads перечислены входные артефакты, которых нет в хранилище. Уже сохранённый контент не нужно загружать повторно.

Загрузите байты и запустите задание #

Для каждой записи uploads отправьте запрос PUT с аутентификацией по адресу uploadUrl, указав Content-Type: application/octet-stream и исходные байты в теле запроса. До запуска задания загрузите исходные файлы и все предыдущие файлы, на которые вы ссылаетесь.

Размер каждого артефакта — не более 25 МиБ. При несовпадении хеша возвращается ArtifactChecksumMismatch, а при превышении размера файла — RequestBodyTooLarge. Если вычислить хеш текста, а затем перед загрузкой изменить окончания строк, байты изменятся и файл не пройдёт проверку.

Вызовите POST /v2/localization/jobs/:id/start после успешной загрузки всех файлов. Артефакты принимаются только до запуска задания. Проверьте ход выполнения задания по целевым языкам, затем скачайте готовые файлы по полученным URL.

Обновите существующий документ #

Для инкрементального обновления сохраните три набора входных данных: новый исходный файл, предыдущий исходный файл и текущий перевод для каждой целевой локали. Передайте:

  • source: адрес артефакта нового исходного файла.
  • previousSource: адрес исходного файла, использованного для предыдущей версии.
  • previousTranslations: по одной записи { "locale": "de", "artifact": "..." } для каждого доступного перевода.

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

Для запроса с ограниченной областью видимости через keyScope или termScope нужен предыдущий перевод для каждой целевой локали. JSON, JSONC, TypeScript и PHP заново генерируют выбранные строки, в том числе с неизменёнными исходными значениями, и объединяют их с существующим переводом. YAML, YAML с локалью в корне и OpenAPI YAML могут повторно использовать выбранный неизменённый контент, если передан предыдущий исходный файл. XCStrings может повторно использовать встроенные или переданные значения перевода даже без предыдущего исходного файла. Поэтому выбранная единица текста не всегда требует нового перевода.

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

Перед созданием следующего задания сохраните базовый файл: отправьте запрос PUT /v2/organizations/:orgId/localization/artifacts/:address с аутентификацией и байтами файла в теле. Для этого маршрута нужен доступ к переводу через движок организации. В ответ он возвращает метаданные артефакта. Действуют то же ограничение в 25 МиБ и та же проверка хеша.

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