Перевод JSON
Отправьте JSON-объект с контекстом, подсказками и защищёнными путями, а затем скачайте переводы.
Передайте JSON-объект прямо в задании на локализацию, если исходные данные уже находятся в памяти приложения. Lingo.dev сохранит его как JSON-документ и создаст отдельный результат для каждой целевой локали.
В кратком руководстве есть полный пример программы. В этом справочнике описаны поля запроса для работы с JSON.
Отправьте документ в теле запроса #
Создайте задание по адресу POST /v2/organizations/:orgId/localization/jobs. Укажите ключ API в X-API-Key и стабильное значение Idempotency-Key для этой отправки:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "settings.json",
"format": {
"type": "json",
"options": {
"context": "Settings dialog in a team collaboration application",
"hints": { "$.save": ["Button that saves the edited settings"] },
"lockedKeys": ["$.productName"]
}
},
"source": {
"content": {
"save": "Save changes",
"cancel": "Cancel",
"productName": "Acme"
}
}
}
]
}Исходные данные должны быть JSON-объектом. Он может содержать вложенные объекты и массивы. Строковые значения в конечных узлах могут быть переведены, а числа, логические значения и null сохраняют свои типы JSON. Защитите строковые идентификаторы, названия продуктов и URL, если они должны остаться без изменений.
Для исходных данных в теле запроса используется format.type: "json". Для JSONC или другого файлового формата загрузите байты файла.
Добавьте контекст и выберите содержимое #
Укажите параметры JSON в format.options документа:
| Параметр | Что делает |
|---|---|
context | Непустой текст с описанием назначения содержимого или его аудитории. |
hints | Запросы JSONPath, каждому из которых соответствует непустой массив непустых подсказок. К выбранным строкам применяются все подходящие подсказки вместе. По умолчанию — пустой объект. |
lockedKeys | Копирует выбранные исходные значения без перевода. По умолчанию — []. |
preservedKeys | Повторно использует выбранные значения из предыдущего перевода, если они доступны. Иначе копирует исходные значения. По умолчанию — []. |
ignoredKeys | Удаляет выбранные значения из результата. По умолчанию — []. |
keyScope | Заново генерирует строки, выбранные с помощью непустого списка запросов JSONPath. Требуется предыдущий перевод для каждой целевой локали. |
termScope | Заново генерирует строки, соответствующие непустому списку исходных терминов. Требуется предыдущий перевод для каждой целевой локали. |
injectLocale | Записывает целевую локаль по одному пути JSONPath, например $.meta.locale. Это поддерево защищено от перевода. |
В запросах API используйте JSONPath. $.title выбирает свойство корневого объекта, $.nav.home — вложенное свойство, $['nav.home'] — ключ с точкой в имени, а $..productName — это свойство на любой глубине. При выборе объекта или массива выбираются и все вложенные строки. Просто имена ключей без синтаксиса JSONPath недопустимы в запросах API.
Правила обработки ключей применяются до перевода. Игнорируемые значения удаляются, а исходные значения, защищённые от перевода, имеют приоритет над сохраняемыми значениями предыдущего перевода. Выбор области перевода не отменяет эти правила. Подробнее о сборке результата и сообщениях ICU — в справочнике по формату JSON.
termScope ищет подстроки в исходных строках с учётом регистра. Для выбора строки достаточно совпадения с любым термином из списка: "cat" также соответствует "catalog", а "login" не соответствует "Login". Заново генерируется вся выбранная строка, а не только совпавший термин. Если указаны и keyScope, и termScope, строка должна соответствовать обоим условиям. Если поиск по подстроке захватывает посторонние сообщения, выберите нужные ключи с помощью точного запроса JSONPath.
Запустите задание и получите результат #
Сохраните id из ответа на создание задания. Если задание также ссылается на предыдущие файлы или другие документы, загрузите каждый элемент из uploads, затем вызовите POST /v2/localization/jobs/:id/start.
Прочитайте GET /v2/localization/jobs/:id и проверьте targets каждого документа. У результата для целевой локали с status._tag: "Completed" есть status.downloadUrl. Чтобы получить JSON-объект, скачайте данные по этому URL с той же аутентификацией. Сам ответ задания содержит сведения о ходе выполнения и адреса артефактов, а не переведённый объект.
Для обновления отправьте артефакты предыдущего исходного документа и перевода, как описано в разделе «Как обновить существующий документ». Сохраните новую версию исходного документа вместе с ИД задания, чтобы запоздавший результат не заменил более новое содержимое.