Перевод JSON

Отправьте JSON-объект с контекстом, подсказками и защищёнными путями, а затем скачайте переводы.

Передайте JSON-объект прямо в задании на локализацию, если исходные данные уже находятся в памяти приложения. Lingo.dev сохранит его как JSON-документ и создаст отдельный результат для каждой целевой локали.

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

Отправьте документ в теле запроса #

Создайте задание по адресу POST /v2/organizations/:orgId/localization/jobs. Укажите ключ API в X-API-Key и стабильное значение Idempotency-Key для этой отправки:

json
{
  "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 с той же аутентификацией. Сам ответ задания содержит сведения о ходе выполнения и адреса артефактов, а не переведённый объект.

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