Ключевые понятия

Язык, алиас, провайдер, маппинг — и один инвариант, делающий резолвинг функцией.

Четыре сущности. Всё остальное в API — представления над ними.

Язык (Language)

Язык, который платформа умеет переводить, идентифицированный каноническим кодом в регистре BCP-47: en, pt-BR, zh-Hans, sr-Latn.

Языки бывают двух видов:

base — без квалификатора: en, de, ceb. Его собственный код и есть то, что получают провайдеры; настраивать нечего.
regional — несёт скрипт, регион или оба: pt-BR, zh-Hans, sr-Latn-RS. Именно о них провайдеры не согласны между собой, и именно ради них существует каталог.

Региональный язык указывает на свой базовый (pt-BR → pt) — это и делает возможным фолбэк из Resolution Ladder.

Почему

ceb — это base «Base» означает без квалификатора, а не две буквы. Канонический код себуанского — ceb: три буквы, без скрипта, без региона. Поэтому он ведёт себя как en и не требует строки на провайдера.

Алиас (Alias)

Любое другое написание, резолвящееся в язык. Алиасы хранятся нормализованными — нижний регистр, разделитель -, — а сверка игнорирует регистр и разделители, так что pt_BR совпадает с алиасом pt-br без отдельной строки.

Они покрывают те написания, которые встречаются на практике: коды ISO 639-2/3 (deu, ger, zho), устаревшие ISO 639-1 (iw → he, in → id), которые до сих пор бывают в экспортах TMS, и всё прочее, с чем приходит конкретная интеграция.

Алиас принадлежит ровно одному языку

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

См. Aliases and Normalisation.

Провайдер (Provider)

Движок перевода, идентифицированный тем же кодом, что и в provider_credentials: deepl_api, openai_api, microsoft_translator.

Провайдер также откликается на свои алиасы — короткое имя (deepl) и любой другой идентификатор, который вызывающие, как известно, шлют для этого движка. Каждый из них резолвится в того же провайдера, так что нормализовать на своей стороне не нужно. GET /v1/providers/{code} возвращает их все.

Поддержка языков — это свойство эндпоинта вендора, а не модели за ним, поэтому один провайдер покрывает все модели, которые этот эндпоинт обслуживает: provider_credentials уже держит модель как поле model_id под одним кредом.

Каждый провайдер также несёт fallback policy — что делать с региональным языком, который никто не настроил. См. Fallback Policies.

Маппинг (Mapping)

Одна строка: этот провайдер, этот язык, этот код.

Две вещи о маппингах удивляют:

Это оверрайды, а не матрица поддержки. Отсутствующая строка означает «нечего сказать отдельно», а не «не поддерживается». Большинству языков строка не нужна вовсе — базовый язык резолвится в собственный код. Действительно неподдерживаемые пары фиксируются явно, с is_supported: false.

На пару он ровно один. Это инвариант, на котором построен сервис: (провайдер, язык) уникальна, поэтому во время запроса выбирать нечего. Каким бы ни был ответ, он каждый раз тот же, а match говорит, как он получен.

Как это складывается

входящий код ──нормализация──▶ алиас ──▶ ЯЗЫК ◀── базовый язык
                                          │
имя провайдера ──нормализация──▶ алиас ──▶ ПРОВАЙДЕР
                                          │
                                    МАППИНГ (провайдер, язык) ──▶ код в запрос
                                          │
                              (отсутствует) ──▶ fallback policy

Resolution Ladder — точный порядок поиска
Language Catalog — что в каталоге и откуда оно
Errors and Conventions — форматы ответов, версионирование, кеширование