Ключові поняття
Мова, аліас, провайдер, мапінг — і один інваріант, що робить резолвінг функцією.
Чотири сутності. Все інше в 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
Далі
- Resolution Ladder — точний порядок пошуку
- Language Catalog — що в каталозі й звідки воно
- Errors and Conventions — формати відповідей, версіонування, кешування