langcode-turner 0.1.13
langcode turn, support iso 639-1, iso 639-2, iso 639-3
Requires Python: >=3.6

# langcode_turner

langcode_turner is a lightweight language code conversion library. It supports multiple standards and platform-specific codes, and provides name-based search.

Common examples:

- ISO 639-1 → ISO 639-3: `en` → `eng`
- ISO 639-3 → ISO 639-1: `est` → `et`

## Features

- Convert between ISO 639-1 / 639-2B / 639-2T / 639-3
- Platform language codes for major translation providers
- Search by language name
- Built-in cache and indexes for high-frequency usage

## Supported Code Types

- ISO 639-1
- ISO 639-2B
- ISO 639-2T
- ISO 639-3
- Platform codes: Baidu / Aliyun / DeepL / Tencent / Huawei / ARC / Google
- IDS (The Intercontinental Dictionary Series)

## Installation

```bash
pip install langcode_turner
```

## Quick Start

```python
from langcode_turner import langcode_turner

converter = langcode_turner("est")
print(converter.iso_639_3)
```

More examples:

```python
from langcode_turner import langcode_turner

# Auto-detect input type
print(langcode_turner("en").to_iso_639_3())
print(langcode_turner("eng").to_iso_639_1())
print(langcode_turner("Chinese").iso_639_3)

# Platform codes
print(langcode_turner("zh").to_baidu_code())
print(langcode_turner("en").to_deepl_code())

# WordNet code
print(langcode_turner("Chinese").wordnet())

# One-line conversion via static method
print(langcode_turner.convert("en", to_type="iso_639_3"))

# Name search
results = langcode_turner.search_languages("chinese")
print(results[:3])
```

## API

### `langcode_turner(langcode: str, code_type: Optional[str] = None)`

Create a converter instance.

- `langcode`: input code or language name
- `code_type`: optional, explicitly specify input type (auto-detect by default)

Auto-detect rules:

- length 2 → `iso_639_1`
- length 3 → `iso_639_3`
- otherwise → language name `ref_name`

### Common Attributes

- `iso_639_1`
- `iso_639_2b`
- `iso_639_2t`
- `iso_639_3`
- `ref_name`
- `ids_code`
- `baidu_lang_code`
- `aliyun_lang_code`
- `deepl_lang_code`
- `tencent_lang_code`
- `huawei_lang_code`
- `arc_lang_code`
- `google_lang_code`

### Helper Methods

These methods raise `ValueError` if the target code is not available:

- `to_iso_639_1()`
- `to_iso_639_2b()`
- `to_iso_639_2t()`
- `to_iso_639_3()`
- `to_baidu_code()`
- `to_aliyun_code()`
- `to_deepl_code()`
- `to_tencent_code()`
- `to_huawei_code()`
- `to_arc_code()`
- `to_google_code()`
- `to_ids_code()`

### `wordnet()`

Returns the WordNet language code.

- If `iso_639_3 == "zho"`, returns `cmn-Hans`
- Otherwise returns `iso_639_1`

### `convert(langcode, from_type=None, to_type="iso_639_3")`

Static method for direct conversion.

```python
langcode_turner.convert("en", to_type="iso_639_3")
```

### `get_all_languages()`

Returns the full language list (raw CSV row structure).

### `search_languages(query)`

Fuzzy search by language name, returns matched rows.

## Error Handling

Raises `ValueError` when:

- Input code/name is not found
- Target code type is not available for the language
- `to_type` is unknown

Example:

```python
try:
	code = langcode_turner("jpn").to_iso_639_1()
except ValueError:
	code = None
```

## Data Source

Language data is stored inside the package:

- `langcode_turner/data/langcode.csv`

Loaded and cached on first use.

## Performance

Built-in class-level cache and indexes provide O(1) lookups after first load.
For benchmarking:

```bash
python performance_test.py
```

## Compatibility

- Python >= 3.6

## Development & Testing

Run unit tests:

```bash
python -m unittest test/unit_test.py
```

## Changelog

- v0.0.1 build code
- v0.0.2 - v0.0.6 fix error
- v0.0.6 a normal version
- v0.0.7 add baidu langcode
- v0.0.8-9 add ids language code support
- v0.1.0 change some function name and add unittest
- v0.1.1-2 fix a ids_id error, the ids_id type change to str.
- v0.1.3 fix a bug, add ci/cd gitlab
- v0.1.4 fix a language name can't find out code bug.
- v0.1.5 fix a bug, add language code name.
- v0.1.6 fix a bug, add language code name, add wordnet().
- v0.1.9 rebuild the code, fix a bug, add search_languages() method.

## License

MIT License

## Author

Feliks Peegel

---

# 中文说明

langcode_turner 是一个轻量的语言代码转换库，支持在多种标准/平台语言代码之间互转，并提供名称搜索能力。

常见示例：

- ISO 639-1 → ISO 639-3：`en` → `eng`
- ISO 639-3 → ISO 639-1：`est` → `et`

## 特性

- 支持 ISO 639-1 / 639-2B / 639-2T / 639-3 互转
- 支持多家翻译平台语言代码
- 支持通过语言名称搜索与查找
- 内置缓存与索引，适合高频调用

## 支持的代码类型

- ISO 639-1
- ISO 639-2B
- ISO 639-2T
- ISO 639-3
- 平台代码：Baidu / Aliyun / DeepL / Tencent / Huawei / ARC / Google
- IDS (The Intercontinental Dictionary Series)

## 安装

```bash
pip install langcode_turner
```

## 快速开始

```python
from langcode_turner import langcode_turner

converter = langcode_turner("est")
print(converter.iso_639_3)
```

更多示例：

```python
from langcode_turner import langcode_turner

# 自动识别输入类型
print(langcode_turner("en").to_iso_639_3())
print(langcode_turner("eng").to_iso_639_1())
print(langcode_turner("Chinese").iso_639_3)

# 平台代码
print(langcode_turner("zh").to_baidu_code())
print(langcode_turner("en").to_deepl_code())

# WordNet 代码
print(langcode_turner("Chinese").wordnet())

# 静态方法一行转换
print(langcode_turner.convert("en", to_type="iso_639_3"))

# 名称搜索
results = langcode_turner.search_languages("chinese")
print(results[:3])
```

## API 说明

### `langcode_turner(langcode: str, code_type: Optional[str] = None)`

初始化转换器实例。

- `langcode`：输入代码或语言名称
- `code_type`：可选，显式指定类型（默认自动检测）

自动检测规则：

- 长度为 2 → `iso_639_1`
- 长度为 3 → `iso_639_3`
- 其它 → 语言名称 `ref_name`

### 常用属性

- `iso_639_1`
- `iso_639_2b`
- `iso_639_2t`
- `iso_639_3`
- `ref_name`
- `ids_code`
- `baidu_lang_code`
- `aliyun_lang_code`
- `deepl_lang_code`
- `tencent_lang_code`
- `huawei_lang_code`
- `arc_lang_code`
- `google_lang_code`

### 便捷方法

这些方法在目标代码不存在时会抛出 `ValueError`：

- `to_iso_639_1()`
- `to_iso_639_2b()`
- `to_iso_639_2t()`
- `to_iso_639_3()`
- `to_baidu_code()`
- `to_aliyun_code()`
- `to_deepl_code()`
- `to_tencent_code()`
- `to_huawei_code()`
- `to_arc_code()`
- `to_google_code()`
- `to_ids_code()`

### `wordnet()`

返回 WordNet 语言代码。

- 当 `iso_639_3 == "zho"` 时返回 `cmn-Hans`
- 其他语言返回 `iso_639_1`

### `convert(langcode, from_type=None, to_type="iso_639_3")`

静态方法，直接完成一次转换。

```python
langcode_turner.convert("en", to_type="iso_639_3")
```

### `get_all_languages()`

返回完整语言列表（CSV 原始行结构）。

### `search_languages(query)`

根据语言名称进行模糊搜索，返回匹配的语言列表。

## 错误处理

以下场景会抛出 `ValueError`：

- 输入的语言代码/名称不存在
- 目标代码类型在该语言中不可用
- `to_type` 指定未知目标类型

建议在批量处理时使用 `try/except` 捕获：

```python
try:
	code = langcode_turner("jpn").to_iso_639_1()
except ValueError:
	code = None
```

## 数据来源

语言数据存储在包内 CSV：

- `langcode_turner/data/langcode.csv`

库会在首次使用时加载并缓存数据。

## 性能说明

库内置类级缓存与索引，首次加载后查询为 O(1) 查找，适合高频调用。
如需基准测试可运行：

```bash
python performance_test.py
```

## 兼容性

- Python >= 3.6

## 开发与测试

运行单元测试：

```bash
python -m unittest test/unit_test.py
```

## 更新日志

- v0.0.1 build code
- v0.0.2 - v0.0.6 fix error
- v0.0.6 a normal version
- v0.0.7 add baidu langcode
- v0.0.8-9 add ids language code support
- v0.1.0 change some function name and add unittest
- v0.1.1-2 fix a ids_id error, the ids_id type change to str.
- v0.1.3 fix a bug, add ci/cd gitlab
- v0.1.4 fix a language name can't find out code bug.
- v0.1.5 fix a bug, add language code name.
- v0.1.6 fix a bug, add language code name, add wordnet().
- v0.1.9 rebuild the code, fix a bug, add search_languages() method.

## License

MIT License

## Author

Feliks Peegel