### Install with Poetry

Source: https://github.com/rspeer/langcodes/blob/master/README.md

When installing the package in editable mode before PEP 660 is fully supported, use `poetry install` instead of `pip install -e .`.

```bash
poetry install
```

--------------------------------

### Language.describe()

Source: https://context7.com/rspeer/langcodes/llms.txt

Get all component names as a dictionary. Returns a dictionary with 'language', 'script', and/or 'territory' keys, each with their natural-language name in the target language. Requires language_data.

```APIDOC
## `Language.describe()` — Get all component names as a dictionary

Returns a dictionary with `'language'`, `'script'`, and/or `'territory'` keys, each with their natural-language name in the target language. Requires `language_data`.

```python
from langcodes import Language

shaw = Language.make(script='Shaw').maximize()

print(shaw.describe('en'))
# {'language': 'English', 'script': 'Shavian', 'territory': 'United Kingdom'}

print(shaw.describe('fr'))
# {'language': 'anglais', 'script': 'shavien', 'territory': 'Royaume-Uni'}

print(shaw.describe('es'))
# {'language': 'inglés', 'script': 'shaviano', 'territory': 'Reino Unido'}

print(shaw.describe('zh-Hans'))
# {'language': '英语', 'script': '萧伯纳式文', 'territory': '英国'}

print(shaw.describe('ja'))
# {'language': '英語', 'script': 'ショー文字', 'territory': 'イギリス'}

print(shaw.describe('arb'))
# {'language': 'الإنجليزية', 'script': 'الشواني', 'territory': 'المملكة المتحدة'}

# Falls back to English for unknown display languages
print(shaw.describe('lol'))
# {'language': 'English', 'script': 'Shavian', 'territory': 'United Kingdom'}
```
```

--------------------------------

### Describe Language Code Components in English

Source: https://github.com/rspeer/langcodes/blob/master/README.md

Get a dictionary of the language, script, and territory components of a language code, described in English. Requires the `Language` object.

```python
from langcodes import Language

shaw = Language.get('en-Shaw-GB')
print(shaw.describe('en'))
```

--------------------------------

### Describe Language Code Components in Spanish

Source: https://github.com/rspeer/langcodes/blob/master/README.md

Get a dictionary of the language, script, and territory components of a language code, described in Spanish. Requires the `Language` object.

```python
from langcodes import Language

shaw = Language.get('en-Shaw-GB')
print(shaw.describe('es'))
```

--------------------------------

### Get Writing Population for Languages

Source: https://context7.com/rspeer/langcodes/llms.txt

Retrieves the writing population for a given language tag. Demonstrates territory-scoped populations and how to avoid normalization for raw totals.

```python
from langcodes import Language

all_zh   = Language.get('zh').writing_population()        # 1240841517
trad_zh  = Language.get('zh-Hant').writing_population()   # 36863340
simp_zh  = Language.get('zh-Hans').writing_population()
print(all_zh == trad_zh + simp_zh)   # True

# Territory-scoped writing
print(Language.get('zh-Hant-HK').writing_population())    # 6439733
print(Language.get('zh-Hans-HK').writing_population())    # 338933

# Avoid normalization to get the raw total for zh-HK
print(Language.get('zh-HK', normalize=False).writing_population())  # 6778666
```

--------------------------------

### Get Alpha3 Language Codes

Source: https://github.com/rspeer/langcodes/blob/master/README.md

Use `to_alpha3()` to get the 3-letter ISO 639-2 terminology code by default. Pass `variant='B'` to get the bibliographic code. This method always returns a 3-letter string.

```python
Language.get('fr').to_alpha3()
# Output: 'fra'
```

```python
Language.get('fr-CA').to_alpha3()
# Output: 'fra'
```

```python
Language.get('fr-CA').to_alpha3(variant='B')
# Output: 'fre'
```

```python
Language.get('de').to_alpha3()
# Output: 'deu'
```

```python
Language.get('no').to_alpha3()
# Output: 'nor'
```

```python
Language.get('un').to_alpha3()
# Traceback (most recent call last):
#     ...
# LookupError: 'un' is not a known language code, and has no alpha3 code.
```

```python
Language.get('en').to_alpha3(variant='T')
# Output: 'eng'
```

```python
Language.get('en').to_alpha3(variant='B')
# Output: 'eng'
```

--------------------------------

### Get Language Name in Target Language

Source: https://context7.com/rspeer/langcodes/llms.txt

Demonstrates how to get the natural language name of a language code, potentially in a different language than the code itself. Useful for displaying language names in a user's preferred locale.

```python
print(Language.get('sl').language_name('sl'))   # slovenščina
print(Language.get('sk').language_name('sk'))   # slovenčina
print(Language.get('sl').language_name('sk'))   # slovinčina
print(Language.get('sk').language_name('sl'))   # slovaščina
```

--------------------------------

### Language.make()

Source: https://context7.com/rspeer/langcodes/llms.txt

Constructs a Language object from individual BCP 47 subtag components. Results are cached, ensuring object identity is preserved for identical arguments.

```APIDOC
## Language.make()

### Description
Creates a `Language` object from individual BCP 47 subtag components. Results are cached: calling `make()` twice with the same arguments returns the same object. Useful for programmatically building language tags.

### Method Signature
`Language.make(language: str = None, script: str = None, territory: str = None, variants: list[str] = None, extensions: list[str] = None, private: str = None) -> Language`

### Parameters
#### Path Parameters
None

#### Query Parameters
* `language` (str) - Optional - The primary language subtag.
* `script` (str) - Optional - The script subtag.
* `territory` (str) - Optional - The territory subtag.
* `variants` (list[str]) - Optional - A list of variant subtags.
* `extensions` (list[str]) - Optional - A list of extension subtags.
* `private` (str) - Optional - The private use subtag.

### Request Example
```python
from langcodes import Language

# Build from components
lang = Language.make(language='zh', script='Hant', territory='TW')
print(lang)           # zh-Hant-TW

# Minimal: just a territory
print(Language.make(territory='IN'))    # und-IN

# With variants
lang = Language.make(language='en', territory='GB', variants=['oxendict'])
print(lang)     # en-GB-oxendict

# With private use subtag
lang = Language.make(language='nan', private='x-zh-min')
print(lang)     # nan-x-zh-min

# With Unicode extension
lang = Language.make(language='en', extensions=['u-co-backward'])
print(lang)     # en-u-co-backward

# Object identity is preserved (cached)
a = Language.make(language='fr', territory='CA')
b = Language.make(language='fr', territory='CA')
print(a is b)   # True
```

### Response
#### Success Response (Language Object)
Returns a `Language` object constructed from the provided components.

#### Response Example
```
zh-Hant-TW
und-IN
en-GB-oxendict
nan-x-zh-min
en-u-co-backward
True
```
```

--------------------------------

### Get Language Display Name

Source: https://context7.com/rspeer/langcodes/llms.txt

Use `Language.display_name()` to get a human-readable name for a language tag. It can display the name in a specified target language and requires the `language_data` package. Unknown language codes are handled gracefully.

```python
from langcodes import Language

# Default: English
print(Language.make(language='fr').display_name())      # French
print(Language.get('zh-Hans').display_name())           # Chinese (Simplified)
print(Language.get('en-US').display_name())             # English (United States)
print(Language.make().display_name())                   # Unknown language

# Named in other languages
print(Language.get('fr').display_name('fr'))            # français
print(Language.get('fr').display_name('es'))            # francés
print(Language.get('zh-Hans').display_name('de'))       # Chinesisch (Vereinfacht)
print(Language.get('en-US').display_name('zh-Hans'))    # 英语（美国）
print(Language.make().display_name('es'))               # lengua desconocida

# Unknown language code placeholders
print(Language.get('xyz-ZY').display_name())
# Unknown language [xyz] (Unknown Region [ZY])
print(Language.get('xyz-ZY').display_name('es'))
# lengua desconocida [xyz] (Región desconocida [ZY])

# Normalized tags display their normalized form's name
print(Language.get('sh').display_name())                # Serbian (Latin)
print(Language.get('sh', normalize=False).display_name())  # Serbo-Croatian
```

--------------------------------

### Convert Language to Alpha3

Source: https://github.com/rspeer/langcodes/blob/master/README.md

The `Language.to_alpha3()` method provides a way to get the three-letter code for a language according to ISO 639-2.

```python
>>> Language.to_alpha3()

```

--------------------------------

### Construct Language Object with Language.make()

Source: https://context7.com/rspeer/langcodes/llms.txt

Use `Language.make()` to programmatically build `Language` objects from individual BCP 47 subtag components. Results are cached, ensuring object identity is preserved for identical arguments.

```python
from langcodes import Language

# Build from components
lang = Language.make(language='zh', script='Hant', territory='TW')
print(lang)           # zh-Hant-TW
print(str(lang))      # zh-Hant-TW
print(repr(lang))     # Language.make(language='zh', script='Hant', territory='TW')

# Minimal: just a territory
print(Language.make(territory='IN'))    # und-IN

# With variants
lang = Language.make(language='en', territory='GB', variants=['oxendict'])
print(lang)     # en-GB-oxendict

# With private use subtag
lang = Language.make(language='nan', private='x-zh-min')
print(lang)     # nan-x-zh-min

# With Unicode extension
lang = Language.make(language='en', extensions=['u-co-backward'])
print(lang)     # en-u-co-backward

# Object identity is preserved (cached)
a = Language.make(language='fr', territory='CA')
b = Language.make(language='fr', territory='CA')
print(a is b)   # True
```

--------------------------------

### Get Autonym (Native Name) of a Language

Source: https://github.com/rspeer/langcodes/blob/master/README.md

The `autonym()` method returns the display name of a language in the language itself, using CLDR data.

```python
Language.get('fr').autonym()
# Output: 'français'
```

```python
Language.get('es').autonym()
# Output: 'español'
```

```python
Language.get('ja').autonym()
# Output: '日本語'
```

```python
Language.get('en-AU').autonym()
# Output: 'English (Australia)'
```

```python
Language.get('sr-Latn').autonym()
# Output: 'srpski (latinica)'
```

```python
Language.get('sr-Cyrl').autonym()
# Output: 'српски (ћирилица)'
```

--------------------------------

### Check if Name Data is Available for a Language

Source: https://context7.com/rspeer/langcodes/llms.txt

Checks if CLDR locale data is installed for a language. Useful for safely calling display_name() and autonym().

```python
from langcodes import Language

print(Language.get('fr').has_name_data())    # True
print(Language.get('so').has_name_data())    # True   — Somali
print(Language.get('enc').has_name_data())   # False  — Old English (no CLDR locale)
print(Language.get('und').has_name_data())   # False  — undefined

# Use it to safely call display_name
lang = Language.get('yi')
if lang.has_name_data():
    print(lang.autonym())
else:
    print(lang.to_tag())
```