ISO639 Language Codes

Common errors

• TypeError: Cannot read properties of undefined (reading 'iso639-1')

  cause The language key used to access the `iso` object does not exist, is misspelled, or incorrectly cased.
  fix Ensure the language name matches a key in the `iso` object exactly. Keys are case-sensitive. You can inspect `Object.keys(iso)` to see available language names. Example: `iso['Portuguese']`.

• SyntaxError: Named export 'iso' not found

  cause Attempting to use a named import (`import { iso } from 'iso639-codes';`) when the module exports the entire dataset as a default.
  fix Use a default import statement: `import iso from 'iso639-codes';`

• ReferenceError: iso is not defined

  cause The `iso` variable was used before it was properly imported or required from the package.
  fix Ensure `const iso = require('iso639-codes');` (for CommonJS) or `import iso from 'iso639-codes';` (for ESM) is at the top of your file before `iso` is referenced.

Warnings

• gotcha The language keys used to access data (e.g., 'Portuguese') are case-sensitive. Using incorrect casing will result in `undefined`.
  Fix: Ensure the language name matches the key exactly, as found in the dataset (e.g., by inspecting `Object.keys(iso)`). Example: `iso['Portuguese']` is correct, `iso['portuguese']` is not.
• gotcha The `iso639-1` property might be `null` for some languages if a two-letter (alpha-2) code does not exist for that language.
  Fix: Always check for `null` or `undefined` when accessing `iso639-1` (e.g., `language['iso639-1'] ?? 'N/A'`) if the code is optional for your use case.
• gotcha The package's data source (www.loc.gov/standards/iso639-2) and the package itself are static. While generally stable, rely on regular updates from the maintainer for the data to reflect the latest ISO standards.
  Fix: Monitor the package's GitHub repository for updates and ensure your dependencies are kept up-to-date to receive the latest available language data.

Install

• npm install iso639-codes npm
• yarn add iso639-codes yarn
• pnpm add iso639-codes pnpm

Imports

• iso
  wrong:

  import { iso } from 'iso639-codes';

  correct:

  import iso from 'iso639-codes';

  The entire ISO639 language data set is exported as the default export. Do not use named imports.
• iso (CommonJS)

  const iso = require('iso639-codes');

  For CommonJS environments, the entire dataset is returned when requiring the module.
• Language Data Access
  wrong:

  iso.English.iso639-1

  correct:

  iso['English']['iso639-1']

  Language names are string keys, and properties like 'iso639-1' contain hyphens, requiring bracket notation for access.

Quickstart

This quickstart demonstrates how to import the ISO639 language codes dataset and access specific language information by name, including ISO639-1, ISO639-2 codes, and alternative names. It also shows how to iterate through the available languages.

import iso from 'iso639-codes';

// Accessing specific language data by name
console.log(`Portuguese ISO639-1: ${iso['Portuguese']['iso639-1']}`);
console.log(`Portuguese ISO639-2: ${iso['Portuguese']['iso639-2']}`);

// Some languages may not have an ISO639-1 code (returns null)
console.log(`Balinese ISO639-1: ${iso['Balinese']['iso639-1']}`); // Expected: null

// Accessing alternative names for a language
console.log(`Chichewa names: ${iso['Chichewa'].names.join(', ')}`);

// Iterating through the first few languages in the dataset
console.log('\n--- First 3 languages ---');
let count = 0;
for (const langName in iso) {
  if (count >= 3) break;
  const language = iso[langName];
  console.log(`Name: ${language.name}, ISO639-1: ${language['iso639-1'] ?? 'N/A'}, ISO639-2: ${language['iso639-2']}`);
  count++;
}

// Example of looking up a non-existent language (will be undefined)
const nonExistentLang = iso['Klingon'];
console.log(`\nKlingon data: ${nonExistentLang}`);