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

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

Настраивать ничего не нужно. 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 — один неизвестный язык никогда не стоит вам остального батча.

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

Работают три формы:

Коды каталога — те же, что в provider_credentials, так что один идентификатор работает в обоих сервисах. Легаси-имена существуют, чтобы переезжающие с консоли ничего не меняли в первый день — см. Migrating from the Console.

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

Любое зарегистрированное написание; регистр и разделители игнорируются. 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 — все операции на одной странице