Skip to Content
DocumentationLanguage Codes

Language Codes

GLOST supports flexible language identification using multiple standard formats.

Supported Formats

ISO-639-1 (Two-letter codes)

The most common format with 184 language codes.

"en" // English "th" // Thai "ja" // Japanese

ISO-639-3 (Three-letter codes)

More precise identification covering 7000+ languages.

"eng" // English "tha" // Thai "cmn" // Mandarin Chinese (distinct from "yue" Cantonese)

BCP-47 (Full language tags)

Complete tags with script and region.

"en-US" // English (United States) "zh-Hans-CN" // Chinese (Simplified, China) "sr-Latn-RS" // Serbian (Latin script, Serbia)

Usage

import { // Conversion toISO639_3, toISO639_1, // Names getLanguageName, getNativeLanguageName, // Validation isValidLanguageCode, // BCP-47 parseBCP47, buildBCP47, toBCP47WithRegion, // Info getLanguageInfo, } from "@glotblocks/glost-common"; // All formats accepted toISO639_3("en"); // "eng" toISO639_3("en-US"); // "eng" toISO639_3("eng"); // "eng" // Get language names getLanguageName("th"); // "Thai" getLanguageName("tha"); // "Thai" getLanguageName("cmn"); // "Mandarin Chinese" // Native names getNativeLanguageName("ja"); // "日本語" getNativeLanguageName("th"); // "ไทย" getNativeLanguageName("ar"); // "العربية" // Complete info getLanguageInfo("th"); // { // code: "th", // iso3: "tha", // iso1: "th", // name: "Thai", // nativeName: "ไทย", // bcp47: "tha-TH" // } // BCP-47 parsing parseBCP47("zh-Hans-CN"); // { language: "zh", script: "Hans", region: "CN" } buildBCP47({ language: "sr", script: "Latn", region: "RS" }); // "sr-Latn-RS"

Special Codes

CodeMeaning
ipaInternational Phonetic Alphabet
undUndetermined language
mulMultiple languages

BCP-47 Language Code Utilities (v0.4.0+)

GLOST v0.4.0 introduces comprehensive utilities for working with BCP-47 language codes, providing normalization, matching, and migration support.

Normalization

Convert language codes to standard BCP-47 format:

import { normalizeLanguageCode } from "@glotblocks/glost-common"; // Add default regions normalizeLanguageCode("en"); // "en-US" normalizeLanguageCode("th"); // "th-TH" normalizeLanguageCode("ja"); // "ja-JP" // Convert ISO 639-3 to ISO 639-1 normalizeLanguageCode("tha"); // "th-TH" normalizeLanguageCode("fra"); // "fr-FR" normalizeLanguageCode("eng"); // "en-US" // Already normalized codes remain unchanged normalizeLanguageCode("en-GB"); // "en-GB" normalizeLanguageCode("zh-CN"); // "zh-CN"

Parsing

Parse BCP-47 codes into components:

import { parseLanguageCode } from "@glotblocks/glost-common"; parseLanguageCode("en-US"); // { language: "en", region: "US" } parseLanguageCode("zh-Hans-CN"); // { language: "zh", script: "Hans", region: "CN" } parseLanguageCode("sr-Latn-RS"); // { language: "sr", script: "Latn", region: "RS" }

Matching

Compare language codes with flexible matching:

import { matchLanguage } from "@glotblocks/glost-common"; // Exact match matchLanguage("en-US", "en-US"); // true // Parent language match matchLanguage("en-US", "en"); // true // Different regions matchLanguage("en-GB", "en-US"); // false // Ignore region differences matchLanguage("en-GB", "en-US", { ignoreRegion: true }); // true

Finding Best Matches

Find the best matching language code from available options:

import { findBestMatch } from "@glotblocks/glost-common"; const available = ["en-US", "en-GB", "fr-FR", "th-TH"]; findBestMatch("en-GB", available); // "en-GB" (exact) findBestMatch("en-AU", available); // "en-US" (fallback) findBestMatch("en", available); // "en-US" (fallback)

Language Fallbacks

Get fallback language codes in order of preference:

import { getLanguageFallbacks } from "@glotblocks/glost-common"; getLanguageFallbacks("en-GB"); // ["en-GB", "en-US", "en"] getLanguageFallbacks("zh-Hans-CN"); // ["zh-Hans-CN", "zh-CN", "zh"]

Validation

Validate BCP-47 format:

import { isValidBCP47, asBCP47 } from "@glotblocks/glost-common"; isValidBCP47("en-US"); // true isValidBCP47("tha-TH"); // true isValidBCP47("invalid"); // false // Cast with validation const code = asBCP47("en-US"); // Returns BCP47LanguageCode type

Migration

Migrate existing documents to BCP-47 standard:

import { migrateAllLanguageCodes } from "@glotblocks/glost-utils"; const result = migrateAllLanguageCodes(document, { addDefaultRegions: true, convertISO639_3: true }); console.log(`Updated ${result.nodesUpdated} nodes`); result.changes.forEach(change => { console.log(`${change.path}: ${change.oldCode} → ${change.newCode}`); });

Type Safety

Use branded types for compile-time safety:

import type { BCP47LanguageCode } from "@glotblocks/glost-common"; function processLanguage(code: BCP47LanguageCode) { // Type-safe language code handling } // Must use asBCP47 to cast const code = asBCP47("en-US"); processLanguage(code); // ✓ Type-safe

Migration from v0.3.x

If you’re upgrading from v0.3.x, use the migration utility to update your documents:

import { migrateAllLanguageCodes } from "@glotblocks/glost-utils"; import fs from "fs"; // Read existing document const doc = JSON.parse(fs.readFileSync("document.glost.json", "utf-8")); // Migrate language codes const result = migrateAllLanguageCodes(doc, { addDefaultRegions: true, convertISO639_3: true }); // Save if changes were made if (result.hasChanges) { fs.writeFileSync("document.glost.json", JSON.stringify(doc, null, 2)); console.log(`Migrated ${result.nodesUpdated} nodes`); }

| zxx | No linguistic content |

import { isSpecialCode, SPECIAL_CODES } from "@glotblocks/glost-common"; isSpecialCode("ipa"); // true isSpecialCode("en"); // false SPECIAL_CODES; // ["ipa", "und", "mul", "zxx"]

Complete Language List

Major World Languages

ISO-639-1ISO-639-3LanguageNative Name
enengEnglishEnglish
esspaSpanishEspañol
frfraFrenchFrançais
dedeuGermanDeutsch
ititaItalianItaliano
ptporPortuguesePortuguês
rurusRussianРусский
araraArabicالعربية
hihinHindiहिन्दी
bnbenBengaliবাংলা
jajpnJapanese日本語
kokorKorean한국어
vivieVietnameseTiếng Việt
ththaThaiไทย
idindIndonesianBahasa Indonesia
msmsaMalayBahasa Melayu
nlnldDutchNederlands
plpolPolishPolski
trturTurkishTürkçe
ukukrUkrainianУкраїнська

Chinese Varieties

ISO-639-3 distinguishes Chinese varieties that ISO-639-1 cannot:

ISO-639-3LanguageNative Name
zhoChinese (generic)中文
cmnMandarin Chinese普通话
yueCantonese粵語
nanMin Nan Chinese閩南語
wuuWu Chinese吴语
hakHakka Chinese客家話
hsnXiang Chinese湘语
ganGan Chinese贛語
cdoMin Dong Chinese閩東語

European Languages

ISO-639-1ISO-639-3LanguageNative Name
elellGreekΕλληνικά
cscesCzechČeština
roronRomanianRomână
huhunHungarianMagyar
fifinFinnishSuomi
svsweSwedishSvenska
dadanDanishDansk
nonorNorwegianNorsk
bgbulBulgarianБългарски
hrhrvCroatianHrvatski
skslkSlovakSlovenčina
slslvSlovenianSlovenščina
srsrpSerbianСрпски
ltlitLithuanianLietuvių
lvlavLatvianLatviešu
etestEstonianEesti
isislIcelandicÍslenska
gagleIrishGaeilge
cycymWelshCymraeg
cacatCatalanCatalà
eueusBasqueEuskara
glglgGalicianGalego

South Asian Languages

ISO-639-1ISO-639-3LanguageNative Name
tatamTamilதமிழ்
tetelTeluguతెలుగు
mlmalMalayalamമലയാളം
knkanKannadaಕನ್ನಡ
mrmarMarathiमराठी
gugujGujaratiગુજરાતી
papanPunjabiਪੰਜਾਬੀ
ururdUrduاردو
sisinSinhalaසිංහල
nenepNepaliनेपाली

Southeast Asian Languages

ISO-639-1ISO-639-3LanguageNative Name
kmkhmKhmerខ្មែរ
lolaoLaoພາສາລາວ
mymyaBurmeseဗမာစာ
tltglTagalogTagalog
jvjavJavaneseBasa Jawa
susunSundaneseBasa Sunda

Middle Eastern Languages

ISO-639-1ISO-639-3LanguageNative Name
hehebHebrewעברית
fafasPersianفارسی
kukurKurdishKurdî
pspusPashtoپښتو

African Languages

ISO-639-1ISO-639-3LanguageNative Name
swswaSwahiliKiswahili
hahauHausaHausa
yoyorYorubaYorùbá
igiboIgboIgbo
amamhAmharicአማርኛ
zuzulZuluisiZulu
xhxhoXhosaisiXhosa
afafrAfrikaansAfrikaans

Other Languages

ISO-639-1ISO-639-3LanguageNative Name
kakatGeorgianქართული
hyhyeArmenianՀայdelays
azazeAzerbaijaniAzərbaycan
kkkazKazakhҚазақ
uzuzbUzbekOʻzbek
mnmonMongolianМонгол
eoepoEsperantoEsperanto
lalatLatinLatina
sasanSanskritसंस्कृतम्

Default Regions

When converting to BCP-47 with toBCP47WithRegion(), these defaults are used:

LanguageDefault Region
English (en/eng)US
Spanish (es/spa)ES
French (fr/fra)FR
German (de/deu)DE
Portuguese (pt/por)PT
Chinese (zh/zho)CN
Mandarin (cmn)CN
Cantonese (yue)HK
Japanese (ja/jpn)JP
Korean (ko/kor)KR
Thai (th/tha)TH

Type Definitions

// Any language code string type LanguageCode = string; // Validated language codes (Zod schema) type GlostLanguage = "en" | "es" | "fr" | ... | "cmn" | "yue" | "ipa" | "und" | "mul" | "zxx"; // BCP-47 components type BCP47Components = { language: string; // ISO-639 code script?: string; // ISO-15924 script (e.g., "Hans", "Latn") region?: string; // ISO-3166-1 region (e.g., "US", "CN") }; // Language entry in database type LanguageEntry = { name: string; // English name nativeName: string; // Name in the language itself iso1?: string; // ISO-639-1 code if exists };

Validation

import { languageCodeSchema, isValidLanguageCode } from "@glotblocks/glost-common"; // Runtime validation isValidLanguageCode("en"); // true isValidLanguageCode("xyz"); // false // Zod schema validation languageCodeSchema.safeParse("en").success; // true languageCodeSchema.safeParse("xyz").success; // false
Last updated on