Быстрый старт

Один вызов без настройки — и три вещи, которые стоит знать об ответе.

Настраивать ничего не нужно. API публичный, без аутентификации, только на чтение.

Зарезолвить один язык

curl "https://languages.service.custom.mt/v1/resolve?provider=deepl_api&language=pt_BR"

{
  "query": "pt_BR",
  "provider": "deepl_api",
  "language": "pt-BR",
  "code": "PT-BR",
  "supported": true,
  "match": "exact",
  "matched_alias": null,
  "via_language": null
}

code — это ответ, строка для запроса к провайдеру. Остальные поля её объясняют.

Три вещи об этом ответе

code возвращается даже когда он равен вашему вводу. Не делайте отдельный случай для «ничего не изменилось» — всегда отправляйте то, что говорит code. В этом и смысл: ваш код перестаёт знать, какие провайдеры привередливы.

language — канонический код. Храните именно его, а не то написание, которое вы получили. pt_BR, PT-BR и por-br канонизируются в pt-BR, и именно хранение канонической формы делает две записи сравнимыми потом.

match говорит, насколько мы уверены. exact означает, что пару настроили осознанно. Что угодно другое означает, что ответ выведен — корректный и безопасный, но не курированный. Полная лестница — Resolution Ladder.

Вся задача за один раунд-трип

Задаче перевода нужны source и target; проект разворачивает один source на много targets. Спросите всё сразу:

curl -X POST https://languages.service.custom.mt/v1/resolve/batch \
  -H 'Content-Type: application/json' \
  -d '{"pairs":[
        {"provider":"deepl_api","language":"en-GB"},
        {"provider":"deepl_api","language":"pt_BR"}
      ]}'

Порядок ответа совпадает с запросом, и каждый элемент несёт либо result, либо error — один неизвестный язык никогда не стоит вам остального батча.

Как назвать провайдера

Код каталога (deepl_api) — каноническая форма, и он тот же, что в provider_credentials, так что один идентификатор работает в обоих сервисах.

Провайдер также откликается на любой из своих алиасов: короткое имя вроде deepl и любой другой идентификатор, который вызывающие, как известно, шлют для этого движка. GET /v1/providers/{code} возвращает их в поле aliases. Шлите тот, который у вас есть, — все резолвятся в того же провайдера. См. Providers and Vendors.

Как назвать язык

Любое зарегистрированное написание; регистр и разделители игнорируются. zh_hans, ZH-HANS и zh-Hans — один ключ. См. Aliases and Normalisation.

Когда ничего не найдено

{ "error": { "code": "language_not_found",
             "message": "Unknown language code: 'xx-YY'",
             "details": { "language": "xx-YY" } } }

Ветвитесь по error.code, никогда по тексту. Полный перечень — Error Codes.

Если вы чистите список кодов и предпочитаете классифицировать, а не ловить исключения, берите /v1/normalize — он отдаёт 200 с known: false вместо 404. См. Нормализация входящих кодов.

Core Concepts — четыре сущности, которыми оперирует сервис
Resolution Ladder — как вычисляется match
Endpoints Index — все операции на одной странице