Головна/Резолвінг/Драбина резолвінгу ENУКРРУС API-довідник (ReDoc) ↗

Драбина резолвінгу

Точний порядок роботи /v1/resolve і що означає кожне значення match.

Резолвінг — це два пошуки й драбина. Усе працює на снапшоті каталогу в пам'яті: жодного запиту до бази на запит користувача.

Крок 1 — знайти провайдера

Надіслане значення нормалізується і звіряється з кодами провайдерів, далі з їхніми аліасами. Немає збігу — provider_not_found (404).

Крок 2 — знайти мову

Надіслане значення нормалізується (див. Aliases and Normalisation) і звіряється спершу з канонічними кодами, потім з аліасами. Канонічні коди реєструються першими й ніколи не перезаписуються, тож аліас не може затінити справжній код мови.

Якщо точного збігу немає, код поступово скорочується:

zh-Hant-HK  →  zh-hant  →  zh-hk  →  zh

Обидві осі кваліфікаторів присутні, бо провайдери не згодні, яка з них важлива: DeepL хоче zh-Hans, Papago хоче zh-CN. Тег із невідомим кваліфікатором деградує до мови, яку він уточнює, а не падає в 404: de-AT-1996 резолвиться в de-AT, що видно в matched_alias.

Усе одно нічого? language_not_found (404).

Крок 3 — драбина

Тепер, коли обидва відомі, по порядку:

1. exact — явний рядок для цієї пари

Хтось налаштував. Повертаємо його код.

{ "provider": "deepl_api", "language": "zh-CN", "code": "ZH-HANS", "match": "exact" }

Якщо в рядку is_supported: false — зупиняємось: supported: false, code: null. Пара відома як неробоча, запит робити не треба.

2. variant — менш специфічний тег тієї ж мови має рядок

Немає рядка для ar-EG, але є для ar? Беремо його й називаємо у via_language. Baidu пише арабську як ara — такого коду не дало б жодне зрізання тега.

{ "provider": "baidu_translate", "language": "ar-EG", "code": "ara", "match": "variant", "via_language": "ar" }

Якщо знайдений рядок каже is_supported: false, драбина так само зупиняється, а via_language називає мову, чий рядок відмовив. Виграє найконкретніше твердження: провайдер, який не перекладає традиційну китайську, не перекладе й zh-Hant-HK, а перестрибнути відмову до zh означало б відповісти кодом спрощеної.

3. canonical — мова без кваліфікатора

Базова мова не потребує мапінгу: її власний код і є відповіддю.

{ "language": "uk", "code": "uk", "match": "canonical" }

Базова мова без рядка резолвиться сама в себе

Конфігурація мусить казати щось лише про регіональні мови — ті, щодо яких провайдери не згодні. Там, де задокументований перелік мов провайдера записано, рядки мають і базові мови: явний код там, де провайдер пише мову інакше, і явне supported: false там, де він її взагалі не перекладає. У решті випадків власний код мови і є відповіддю, а рядок не потрібен.

4. Fallback policy провайдера

Досягається лише для регіональної мови, для якої нічого не налаштовано. Як обирати — Fallback Policies.

Політика Результат match
base_language код базової мови — pt-BR → pt base_language
passthrough канонічний код без змін passthrough
strict supported: false, code: null —

Усі провайдери зараз їдуть на base_language. Чому strict не є дефолтом — Fallback Policies.

Як читати match на боці викликача

match Рівень довіри Що робити
exact Налаштовано свідомо Використовувати.
variant Налаштовано для близького тега Використовувати. Варто закріпити, якщо повторюється.
canonical Нема чого вирішувати Використовувати.
base_language Виведено — регіон втрачено Використовувати, але якщо регіональна точність критична — перевірте пару.
passthrough Виведено — не перевірено проти цього API Використовувати й стежити за помилками провайдера.

match дорівнює null рівно в одному випадку: supported: false, code: null. Це не рунг драбини, що закінчився, — це записаний факт про пару, і запит не варто робити. via_language каже, чи відмову записано проти самої цієї мови, чи успадковано від менш специфічної.

Більшість викликачів може взагалі ігнорувати match і просто надсилати code. Він для тих, хто не може.

Розібраний приклад

GET /v1/resolve?provider=deepl_api&language=zh_hant_hk

  1. deepl_api збігається з кодом провайдера.
  2. zh_hant_hk нормалізується в zh-hant-hk. Канонічного збігу немає, але саме це написання зареєстроване як аліас zh-HK. Мова = zh-HK, matched_alias: "zh-hant-hk".
  3. У DeepL є явний рядок для zh-HK → ZH-HANT, у власному написанні DeepL великими літерами.
{ "query": "zh_hant_hk", "provider": "deepl_api", "language": "zh-HK",
  "code": "ZH-HANT", "supported": true, "match": "exact",
  "matched_alias": "zh-hant-hk", "via_language": null }

Далі