Home/Languages/Language Catalog ENУКРРУС API Reference (ReDoc) ↗

Language Catalog

What is in the catalog, what each field on a language means, and the rows worth knowing about.

503 languages and 324 inbound aliases, curated for the providers the platform actually uses.

Browsing it

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 matches the name, the canonical code and every alias, so Brazil, pt-br and por-br all find the same row.

Parameter What
q free text over name, canonical code and aliases
kind base or regional
active true hides rows kept for traceability only
limit, offset paging; total in the response is the unpaged count

What a language row carries

Field Meaning
code canonical BCP-47 code — store this one
name English display name
kind base (no qualifier) or regional
base_language_code for a regional variant, the language it qualifies
script, region parsed out of the code, for filtering
is_active false for rows kept for traceability but not usable
also_known_as other names the same language goes by
aliases every inbound spelling that resolves here

code, kind and base_language_code are the three that decide how a pair resolves — see Resolution Ladder. The rest are descriptive.

One language, several names

The same language is often called different things by different tools — "Norwegian (Bokmål)" and "Norwegian (Norway)", "Chinese (Simplified)" and "Chinese (PRC)". The catalog holds one row per language and keeps the other names in also_known_as, so a search by either name still finds it.

Inactive rows

Every row in the catalog is currently active. The active query parameter and the is_active field remain part of the API contract: a language can be deactivated without being deleted, and a caller listing languages to offer should still filter with ?active=true rather than assume the invariant holds forever.

Choosing the canonical code

Where a language has several plausible spellings, the canonical one — the value in code, the one you store — is chosen by:

  1. a usable two-letter ISO 639-1 code, where the language has one,
  2. then fewer subtags — a canonical code should carry no qualifier it does not need. Cebuano is ceb, not ceb-Latn-PH; Serbian Cyrillic is sr-Cyrl, not sr-Cyrl-RS,
  3. then the most textbook BCP-47 spelling.

The dropped qualifiers stay as aliases, so precision is preserved on the way in: ceb-Latn-PH still resolves, and answers ceb.

Note this is not how a provider's outbound code is chosen. What a provider's API accepts is a fact about that API, and shortness is irrelevant to it — see Providers and Vendors.

Pairs answered by the ladder, not by a row

Most (provider, language) pairs are answered by an explicit row nowadays — configured straight from what each provider documents. The rest resolve through the fallback ladder, and that is normal: the ladder shortens a regional tag to the base language its provider certainly understands, and for those pairs that is the right answer.

Where it cannot help is a provider whose accepted codes are not BCP-47 at all. Shortening zh-TW to zh is a reasonable guess in a BCP-47 world; it is simply the wrong vocabulary for an API that spells traditional Chinese cht. Those pairs carry explicit rows:

Provider Language Code Why the ladder could not
baidu_translate zh-TW cht Baidu's own code set — zh, cht, jp, kor
baidu_translate ja jp a base language, so the ladder returns ja unchanged
baidu_translate ko kor same
deepl_api en-GB EN-GB DeepL distinguishes the regional Englishes
deepl_api en-US EN-US same

All five answer match: exact.

baidu_translate + zh-CN deliberately has no row: Baidu's word for simplified Chinese is zh, which is exactly what the ladder derives.

The lesson generalises. If a provider's accepted codes are a vocabulary of their own rather than a spelling convention, expect explicit rows and treat a derived answer there with suspicion — match is what tells you which you got. See Resolution Ladder.

Next