langcodes

Warnings

• deprecated The `best_match` function and other `_score` methods (e.g., `Language.match_score`) are deprecated. They rely on older CLDR matching tables, which are less accurate than the distance-based comparisons introduced later.
  Fix: Use `closest_match` or `Language.distance` for a more accurate measure of language closeness. A lower distance indicates a better match.
• breaking Python 3.8 is no longer supported. Attempting to use `langcodes` on Python 3.8 will likely result in installation failures or unexpected behavior.
  Fix: Upgrade your Python environment to 3.9 or newer. The library's `requires_python` is `>=3.9`.
• gotcha Functions requiring language names (e.g., `Language.display_name()`) or population data now rely on the optional `language-data` package, which is *not* installed by default as of v3.5.1. Attempting to use these features without the optional package will raise an `ImportError`.
  Fix: Install `langcodes` with the `data` extra to include this dependency: `pip install langcodes[data]`.
• gotcha The `Language.__hash__` method was reworked in v3.4.1 to correctly account for all language variations. If you relied on specific hash values or used `Language` objects in sets/dictionaries and persisted/reloaded them across v3.4.1 without re-hashing, you might encounter unexpected behavior due to changed hash values.
  Fix: Ensure `Language` objects are re-hashed or re-created from strings when upgrading from versions prior to 3.4.1 if their hash values are critical to your application logic. As `Language` objects are immutable once created, this primarily affects persistence scenarios or cases where objects are long-lived across upgrades.
• deprecated The `region` parameter, dictionary key, and attribute for `Language` objects were renamed to `territory` to align with CLDR and IANA standards. While some backward compatibility with deprecation warnings exists, relying on `region` is discouraged.
  Fix: Update your code to use `territory` instead of `region` for clarity and future compatibility.

Install

• pip install langcodes Install stable version

Imports

• Language

  from langcodes import Language

• get

  from langcodes import get

  The top-level 'get' function is a convenience alias for Language.get().
• best_match

  from langcodes import best_match

  While still importable, 'best_match' is deprecated and relies on older CLDR matching. Use 'closest_match' or 'Language.distance' instead.

Quickstart

Demonstrates parsing, normalizing, comparing language tags using distance, finding closest matches, and retrieving display names (with an optional dependency).

from langcodes import Language, standardize_tag, closest_match

# Parse a language tag
english_us = Language.get('en-US')
print(f"Parsed 'en-US': language={english_us.language}, script={english_us.script}, territory={english_us.territory}")

# Normalize a language tag
normalized_tag = standardize_tag('zh-CN')
print(f"Normalized 'zh-CN': {normalized_tag}")

# Compare languages using distance (lower is better match)
french = Language.get('fr')
canadian_french = Language.get('fr-CA')
print(f"Distance between 'fr' and 'fr-CA': {french.distance(canadian_french)}")

# Find the closest match from a list of supported languages
desired = 'en-GB'
supported = ['en-US', 'en-AU', 'fr-CA']
closest = closest_match(desired, supported)
print(f"Closest match for '{desired}' in {supported}: {closest}")

# Get display names (requires 'langcodes[data]' to be installed)
try:
    spanish_name_in_english = Language.get('es').display_name('en')
    print(f"Name of 'es' in English: {spanish_name_in_english}")
except ImportError:
    print("Install 'langcodes[data]' (e.g., pip install langcodes[data]) for language names and statistics.")