A TypeScript library for working with language codes based on ISO 639-1, ISO 639-2, and ISO 639-3 standards. Provides comprehensive language data with English names, native names, and various ISO code formats.

Features

✅ Full TypeScript support with comprehensive type definitions
🌍 184 languages with ISO 639-1, 639-2, and 639-3 codes
🏠 Native language names alongside English names
🔍 Flexible search by any language property
📝 Well-documented API with JSDoc comments
🚀 Zero dependencies and lightweight

Installation

npm install lang-codes
# or
bun add lang-codes

Usage

Import

import { 
  allLanguages, 
  hasLanguage, 
  getCodes, 
  getNames, 
  findBy,
  type Language 
} from 'lang-codes';

// Or use the legacy object API
import langs from 'lang-codes';

Get All Languages

const languages = allLanguages();
console.log(languages.length); // 184
console.log(languages[0]);
// {
//   name: "Abkhaz",
//   local: "Аҧсуа", 
//   "1": "ab",
//   "2": "abk",
//   "2T": "abk",
//   "2B": "abk",
//   "3": "abk"
// }

Check Language Existence

// Check by ISO 639-1 code
const hasEnglish = hasLanguage('1', 'en'); // true
const hasKlingon = hasLanguage('name', 'Klingon'); // false

// Check by name
const hasSpanish = hasLanguage('name', 'Spanish'); // true

Get Language Codes

// Get all ISO 639-1 codes
const iso1Codes = getCodes('1');
// ['ab', 'aa', 'af', 'ak', 'sq', ...]

// Get all ISO 639-2 codes
const iso2Codes = getCodes('2');
// ['abk', 'aar', 'afr', 'aka', 'sqi', ...]

// Numeric types also work
const iso3Codes = getCodes(3);
// ['abk', 'aar', 'afr', 'aka', 'sqi', ...]

Get Language Names

// Get English names
const englishNames = getNames(false);
// ['Abkhaz', 'Afar', 'Afrikaans', ...]

// Get native/local names
const nativeNames = getNames(true);
// ['Аҧсуа', 'Afaraf', 'Afrikaans', ...]

Find Specific Languages

// Find by ISO 639-1 code
const english = findBy('1', 'en');
// {
//   name: "English",
//   local: "English",
//   "1": "en",
//   "2": "eng",
//   "2T": "eng",
//   "2B": "eng",
//   "3": "eng"
// }

// Find by name
const spanish = findBy('name', 'Spanish');
// {
//   name: "Spanish",
//   local: "Español",
//   "1": "es",
//   "2": "spa",
//   "2T": "spa",
//   "2B": "spa",
//   "3": "spa"
// }

// Find by native name
const french = findBy('local', 'Français');
// {
//   name: "French",
//   local: "Français",
//   "1": "fr",
//   "2": "fra",
//   "2T": "fra",
//   "2B": "fre",
//   "3": "fra"
// }

TypeScript Support

Language Interface

interface Language {
  /** English name of the language */
  name: string;
  /** Local/native name of the language */
  local: string;
  /** ISO 639-1 code (2 characters) */
  "1": string;
  /** ISO 639-2 code (3 characters) */
  "2": string;
  /** ISO 639-2/T code (3 characters, terminologic) */
  "2T": string;
  /** ISO 639-2/B code (3 characters, bibliographic) */
  "2B": string;
  /** ISO 639-3 code (3 characters) */
  "3": string;
}

Type-Safe Code Types

type LanguageCodeType = "1" | "2" | "2T" | "2B" | "3" | 1 | 2 | 3;
type LanguageCriteria = keyof Language;

Type Checking

// ✅ TypeScript will validate these at compile time
const validCode = getCodes('1'); // ✅ Valid
const invalidCode = getCodes('invalid'); // ❌ TypeScript error

const validCriteria = findBy('name', 'English'); // ✅ Valid
const invalidCriteria = findBy('invalid', 'value'); // ❌ TypeScript error

Legacy API

For backward compatibility, the library also exports a legacy object-based API:

import langs from 'lang-codes';

// All functions are available through the langs object
const allLangs = langs.all();
const hasLang = langs.has('1', 'en');
const codes = langs.codes('2');
const names = langs.names(false);
const found = langs.where('name', 'English');

Language Codes Explained

ISO 639-1 ("1"): Two-letter codes (e.g., 'en', 'es', 'fr')
ISO 639-2 ("2"): Three-letter codes (e.g., 'eng', 'spa', 'fra')
ISO 639-2/T ("2T"): Terminologic codes (technical/scientific use)
ISO 639-2/B ("2B"): Bibliographic codes (library/documentation use)
ISO 639-3 ("3"): Comprehensive three-letter codes

Some languages have different 2T and 2B codes (like German: 'deu' vs 'ger'), while others use the same code for both.

Development

To install dependencies:

bun install

To run:

bun run index.ts

License

MIT License