Главная/Начало работы/Ключевые понятия ENУКРРУС API-справочник (ReDoc) ↗

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

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

Четыре сущности. Всё остальное в 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 без отдельной строки.

Источников три:

  • console — каждый код, который легаси-база держала для этого языка, включая написания, проигравшие в неоднозначных парах
  • curated — коды ISO 639-2/3 (deu, ger, zho) и устаревшие ISO 639-1 (iw → he, in → id), которые до сих пор встречаются в экспортах TMS
  • manual — всё, что добавляет оператор, когда появляется интеграция со своим диалектом

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

alias уникален глобально. Входящий резолвинг обязан быть функцией — один код всегда означает один язык. Консоль допускала, чтобы zh-CN был одновременно в «Chinese (PRC)» и «Chinese (Simplified)»; билдер сида выбирает победителя один раз и фиксирует проигравшего в отчёте, а не оставляет подбрасывание монетки на горячем пути.

См. Aliases and Normalisation.

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

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

Строки уровня модели из консоли (OpenAiGPT4o_2024_11_20_Provider, Gemini_2_5_pro_Provider, …) сворачиваются в провайдера API своего вендора, потому что поддержка языков — это свойство эндпоинта вендора, а не чекпоинта за ним, и provider_credentials уже моделирует модель как поле конфигурации model_id под одним кредом. Каждое свёрнутое имя остаётся алиасом провайдера, так что старые идентификаторы работают.

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

Маппинг (Mapping)

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

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

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

На пару он ровно один. Это инвариант, на котором построен сервис:

Что делала легаси-консоль

В консоли translation_provider_supported_region_codes — обычный many-to-many между провайдером и строкой регионального кода. Ничто не мешало привязать одного провайдера к нескольким кодам одного языка, и 446 из 2 467 пар были именно такими — 330 из них с кодами, отличающимися больше чем регистром (es-LA / ES-LA / es-419). Django резолвил это через .first(): какую строку Postgres отдал, ту и взяли. Код, уходивший провайдеру, был фактически произвольным и мог измениться после VACUUM.

Здесь выбор делается один раз при сиде по документированным правилам, каждое написание-проигравший остаётся входящим алиасом (так что ничто, что резолвилось, не перестаёт), а оператор может перезакрепить любую пару из матрицы.

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

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

Далее