Home/Cookbook/Add a New Language ENУКРРУС API Reference (ReDoc) ↗

Add a New Language

A code arrived that we do not know. Decide whether it is a new language or a new alias.

Goal: an integration sent gsw (Swiss German), or a regional variant we do not hold and got language_not_found.

First: is it a new language, or a spelling of one you have?

This is the whole decision, and getting it wrong creates a duplicate that quietly splits your data.

curl ".../v1/normalize?language=gsw"       # known: false — nothing matches at all
curl ".../v1/normalize?language=de-LI"     # known: true, but language.code is "de"
curl ".../v1/languages?q=german"           # what German variants exist?

Warning

known: true does not mean we have that variant A regional code we do not hold degrades to the language it qualifies, so de-LI answers known: true with language.code: "de". That is deliberate — a caller gets a usable answer instead of a 404 — but it means the test for "do we have this variant?" is language.code equal to what you asked for, not known.

  • A different variant with its own translation behaviour → new language.
  • Another spelling of something you have (por-br for pt-BR, cmn for zh) → new alias. Do not create a language.

When unsure, prefer the alias. Merging two languages later is manual work; deleting a stray alias is one click.

Adding an alias

Admin → Languages → the language → Inbound aliases, type it, Add.

Aliases are stored normalised, so POR_BR and por-br are the same row — you only need one.

If the key is taken you get a clear conflict naming the current owner. That is the global-uniqueness rule from Aliases and Normalisation doing its job: an alias resolving to two languages would make inbound resolution a coin flip.

Adding a language

Admin → Languages → Add a language: a code and a name.

Everything else is derived from the code. de-LI becomes:

code:  de-LI        kind:  regional
script: —           region: LI
base_language_code: de

Casing does not matter on input — zh_hant_hk is stored as zh-Hant-HK.

Use the canonical BCP-47 form

Language first, then script (Titlecase), then region (uppercase): sr-Latn-RS, not sr-RS-Latn. The service reorders it anyway, but matching the stored form keeps your own records tidy.

Then check what providers will send it

The new language's page lists every provider and what each would receive. A fresh regional language typically shows base_language everywhere — de-LI → de.

That is a reasonable default. Pin the ones that need it: see Pin a provider code.

Deleting

A language with provider mappings cannot be deleted — you get a conflict naming the count. Clear the mappings first. Deleting through a cascade would silently drop configuration nobody meant to lose.

To retire a language without deleting it, untick Active. It stops appearing in ?active=true listings but keeps resolving, so existing records stay readable.

Next