langcodes

langcodes is a Python library that understands language codes: the IETF language tags (formerly ISO 639 codes) like en, es, and zh-Hans-CN that software uses to identify languages. It parses these tags into structured Language objects, normalizes their many spellings, and answers practical questions such as whether two codes mean the same thing or how well one language matches another.

Beyond parsing, langcodes can describe a language in a human-readable name, standardize inconsistent or deprecated tags, and measure the distance between language tags for best-match selection. It is a small, dependable building block for internationalization, content localization, and any system that has to reconcile the messy reality of how languages are labeled.

What You Get

• A Language object that parses IETF tags into language, script, and region components
• Normalization of inconsistent, deprecated, or mis-cased tags to canonical forms
• Equivalence checks that recognize when two different codes mean the same language
• Language-matching distance scoring to pick the best available language for a user
• Human-readable language names derived from codes

Common Use Cases

• Normalizing user or content language tags to a canonical form
• Matching a user’s preferred languages against your available translations
• Displaying friendly language names from raw codes

Under The Hood

Architecture The core is the Language class in the langcodes package, which parses a tag into components (language, script, region, variants) and exposes methods for normalization, equivalence, description, and distance. Reference data about languages, scripts, and territories is bundled and consulted to answer naming and matching queries, with a separate module handling tag-distance scoring.

Tech Stack Pure Python with minimal dependencies, packaged via pyproject.toml and tested across versions with tox. Language and territory data is embedded so the library works offline. This repository is the maintained fork under georgkrause/langcodes.

Code Quality The package ships a focused test suite (five test files) covering language parsing, alpha-3 handling, Wiktionary language names, and specific regression issues, with Renovate keeping dependencies current. The scope is small and well-defined, which keeps the code approachable.

API Design The API is compact and pythonic: Language.get('en-GB') returns a rich object, and helpers like matching and description read naturally. Because the surface is small and the naming maps directly to IETF concepts, most users are productive within minutes.