Главная/Языки/Каталог языков ENУКРРУС API-справочник (ReDoc) ↗

Каталог языков

Что в каталоге, что означает каждое поле языка и какие строки стоит знать.

503 языка и 324 входящих алиаса, курируемых под тех провайдеров, которыми платформа действительно пользуется.

Просмотр

curl "https://languages.service.custom.mt/v1/languages?q=portuguese"
curl "https://languages.service.custom.mt/v1/languages?kind=regional&limit=50"
curl "https://languages.service.custom.mt/v1/languages/pt-BR"

q ищет по названию, каноническому коду и каждому алиасу, так что Brazil, pt-br и por-br находят ту же строку.

Параметр Что делает
q свободный текст по названию, каноническому коду и алиасам
kind base или regional
active true прячет строки, сохранённые только для трассировки
limit, offset пагинация; total в ответе — количество без пагинации

Что несёт строка языка

Поле Значение
code канонический код BCP-47 — храните именно его
name английское отображаемое название
kind base (без квалификатора) или regional
base_language_code для регионального варианта — язык, который он уточняет
script, region распарсено из кода, для фильтров
is_active false для строк, сохранённых для трассировки, но непригодных
also_known_as другие названия, под которыми известен тот же язык
aliases все входящие написания, резолвящиеся сюда

code, kind и base_language_code — три поля, которые решают, как зарезолвится пара; см. Resolution Ladder. Остальные описательные.

Один язык, несколько названий

Один и тот же язык разные инструменты часто называют по-разному — «Norwegian (Bokmål)» и «Norwegian (Norway)», «Chinese (Simplified)» и «Chinese (PRC)». Каталог держит одну строку на язык, а другие названия — в also_known_as, так что поиск по любому из них попадает.

Неактивные строки

Сейчас все строки каталога активны. Параметр active и поле is_active остаются частью контракта API: язык можно деактивировать, не удаляя, поэтому вызывающему, который строит список языков, стоит и дальше фильтровать через ?active=true, а не полагаться на вечность этого инварианта.

Выбор канонического кода

Где язык имеет несколько правдоподобных написаний, каноническое — значение в code, то, которое вы храните, — выбирается так:

  1. пригодный двухбуквенный код ISO 639-1, если язык его имеет,
  2. далее меньше сабтегов — канонический код не должен нести квалификатор, который ему не нужен. Себуанский — ceb, а не ceb-Latn-PH; сербская кириллица — sr-Cyrl, а не sr-Cyrl-RS,
  3. далее самое каноническое написание BCP-47.

Отброшенные квалификаторы остаются алиасами, так что точность на входе сохранена: ceb-Latn-PH по-прежнему резолвится и отдаёт ceb.

Обратите внимание: это не то, как выбирается исходящий код провайдера. Что принимает API провайдера — факт об этом API, и длина здесь ни при чём; см. Providers and Vendors.

Пары, на которые отвечает лестница, а не строка

Большинство пар (провайдер, язык) теперь имеют явную строку — настроенную прямо из того, что документирует каждый провайдер. Остальные резолвятся через лестницу фолбэков, и это нормально: лестница срезает региональный тег до базового языка, который провайдер наверняка понимает, и для таких пар это правильный ответ.

Где она бессильна — это провайдер, чьи принимаемые коды вообще не BCP-47. Срезать zh-TW до zh — разумная догадка в мире BCP-47; но это просто не тот словарь для API, которое пишет традиционный китайский как cht. У таких пар есть явные строки:

Провайдер Язык Код Почему лестница не справилась
baidu_translate zh-TW cht собственный набор кодов Baidu — zh, cht, jp, kor
baidu_translate ja jp базовый язык, поэтому лестница вернула бы ja без изменений
baidu_translate ko kor то же
deepl_api en-GB EN-GB DeepL различает региональные английские
deepl_api en-US EN-US то же

Все пять отвечают match: exact.

У baidu_translate + zh-CN строки намеренно нет: слово Baidu для упрощённого китайского — это zh, ровно то, что выводит лестница.

Урок обобщается. Если принимаемые коды провайдера — это собственный словарь, а не конвенция написания, ждите явных строк и относитесь к выведенному ответу там с подозрением: match и говорит, что именно вы получили. См. Resolution Ladder.

Далее