# 国家中英文名称映射技术文档

## 概述

本模块提供了一个简单的国家中英文名称双向映射功能，支持根据中文名称获取对应的英文名称，或根据英文名称获取对应的中文名称。该功能适用于需要进行国家名称本地化处理的场景，如国际化（i18n）、数据清洗、用户界面显示等。

---

## 文件信息

- **文件编码**：UTF-8
- **语言**：Python 3
- **用途**：国家名称中英互译字典与工具函数

---

## 核心数据结构

### `ecc` 字典：英文 → 中文 映射

```python
ecc = {
    "Afghanistan": "阿富汗",
    "Albania": "阿尔巴尼亚",
    ...
}
```

- **说明**：  
  键为国家的英文全称（标准英文拼写），值为对应的简体中文名称。
- **覆盖范围**：包含全球绝大多数主权国家及部分地区（如中国香港、澳门、台湾）和海外领地。
- **特殊命名示例**：
  - `"Congo (Congo-Kinshasa)"`: 刚果民主共和国（简称“刚果（金）”）
  - `"Korea (South)"` / `"Korea (North)"`: 区分韩国与朝鲜
  - `"Hong Kong"`: 香港（中国）
  - `"Taiwan"`: 台湾（中国）

> ⚠️ 注意：所有条目均基于通用国际认知及中国官方立场进行翻译。

---

### `cec` 字典：中文 → 英文 映射

```python
cec = {v: k for k, v in ecc.items()}
```

- **生成方式**：通过字典推导式将 `ecc` 的键值对反转。
- **作用**：实现从中文国名到英文国名的快速查找。
- **示例**：
  ```python
  cec["中国"] → "China"
  cec["法国"] → "France"
  ```

---

## 功能函数

### `get_en_country_name(country)`

#### 功能
根据输入的中文国家名称返回其对应的英文名称；若未找到匹配项，则原样返回输入值。

#### 参数
| 参数名     | 类型   | 描述                     |
|-----------|--------|--------------------------|
| `country` | str    | 输入的中文国家名称       |

#### 返回值
- 若存在映射：返回对应的英文国家名称（字符串）
- 否则：返回原始输入 `country`

#### 示例
```python
get_en_country_name("中国")           # → "China"
get_en_country_name("德国")           # → "Germany"
get_en_country_name("火星")           # → "火星" （无匹配，原样返回）
```

---

### `get_cn_country_name(country)`

#### 功能
根据输入的英文国家名称返回其对应的中文名称；若未找到匹配项，则原样返回输入值。

#### 参数
| 参数名     | 类型   | 描述                     |
|-----------|--------|--------------------------|
| `country` | str    | 输入的英文国家名称       |

#### 返回值
- 若存在映射：返回对应的中文国家名称（字符串）
- 否则：返回原始输入 `country`

#### 示例
```python
get_cn_country_name("Japan")         # → "日本"
get_cn_country_name("Italy")         # → "意大利"
get_cn_country_name("Mars")          # → "Mars" （无匹配，原样返回）
```

---

## 使用场景

1. **国际化系统中的国家名称本地化**
   - 将数据库中的英文国家名转换为中文展示给用户。
2. **表单数据清洗**
   - 统一用户输入的国家名称格式（如“CHINA”、“中国”、“PRC” → “中国”）。
3. **API 接口适配**
   - 在不同语言系统间传递国家信息时做标准化转换。
4. **报表生成**
   - 自动生成多语言版本的统计报告。

---

## 注意事项

1. **大小写敏感性**  
   当前实现是**完全匹配且区分大小写**的。建议在调用前对输入进行标准化处理（如首字母大写、去除多余空格等）。

   ✅ 建议预处理：
   ```python
   get_cn_country_name(country.strip().title())
   ```

2. **别名支持有限**  
   仅支持字典中明确定义的名称。例如：
   - `"USA"` 不等于 `"United States"`
   - `"UK"` 不等于 `"United Kingdom"`

   如需支持别名，可扩展字典或增加别名映射层。

3. **编码要求**
   - 文件以 UTF-8 编码保存，确保中文字符正确解析。

4. **维护建议**
   - 新增国家或修改译名时，请同步更新 `ecc` 字典，并验证 `cec` 自动生成逻辑是否正常。

---

## 扩展建议

| 功能需求             | 实现建议 |
|----------------------|--------|
| 支持别名（如 USA → 美国） | 添加 `aliases` 字典，预先映射常见别名至标准名称 |
| 不区分大小写查询       | 在函数内部统一转为小写/大写后查询 |
| 返回标准化名称         | 提供 `normalize_country()` 函数输出标准中/英文名 |
| 支持 ISO 国家代码      | 扩展为包含 ISO 3166-1 alpha-2/alpha-3 代码的结构化字典 |

---

## 版权与声明

- 中文译名参考中国官方出版物及外交部标准译法。
- 本数据不用于任何商业目的之外的责任归属。
- “台湾”、“香港”、“澳门”按一个中国原则标注为中国地区。

---

## 示例代码

```python
# 示例：中英文互译
print(get_en_country_name("日本"))        # 输出: Japan
print(get_cn_country_name("Brazil"))      # 输出: 巴西

# 示例：未识别名称原样返回
print(get_cn_country_name("Middle Earth")) # 输出: Middle Earth
```

--- 

✅ **版本状态**：稳定可用  
📅 **最后更新**：2025年4月5日