Головна/Резолвінг/Драбина резолвінгу 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 — менш специфічний тег тієї ж мови має рядок

Немає рядка для zh-Hant-HK, але є для zh-TW? Беремо його й називаємо у via_language.

{ "language": "zh-Hant-HK", "code": "zh-Hant", "match": "variant", "via_language": "zh-TW" }

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

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

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

Це точно повторює консоль

get_lang_code_by_provider_and_language починається з if language.abbreviation: return language.abbreviation — він повертає дволітерний код ще до того, як подивиться на провайдера. Саме тому консоль зберігала коди лише для регіональних мов, і саме тому базова мова без рядка — це норма, а не прогалина.

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

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

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

Усі провайдери зараз їдуть на base_language — це те, що консоль робить сьогодні (lang_region_list.code[:2]). Чому strict не є дефолтом — Fallback Policies.

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

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

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

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

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

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

Спробуйте самі

На сторінці Tools в адмінці є живий тестер, що виконує цей самий код, — можна перевірити пару, не пишучи запит.

Далі