Ключові поняття

Мова, аліас, провайдер, мапінг — і один інваріант, що робить резолвінг функцією.

Чотири сутності. Все інше в 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 — формати відповідей, версіонування, кешування