# Kam Internationalization (i18n) / Language Settings

This document explains how to configure the language for Kam CLI messages. Kam supports English and Chinese (Simplified) for user interface text.

This document contains two sections: English and 中文 (Simplified Chinese).

---

## English

### Overview

Kam provides a lightweight internationalization (i18n) system that supports multiple languages for CLI messages. The language detection follows a priority order, allowing you to override the language at different levels.

### Supported Languages

- **English**: `en`, `en-US`, `en_US`
- **Chinese (Simplified)**: `zh`, `zh-CN`, `zh_CN`

### Language Detection Priority

Kam detects the language in the following order (highest to lowest priority):

1. **Environment Variables** (highest priority)
2. **Config File** (recommended for persistent settings)
3. **System Locale** (auto-detected if available)
4. **LANG Environment Variable** (fallback)
5. **Default** (English if none of the above are set)

### Setting Language via Environment Variables

Environment variables take the highest precedence and are useful for quick one-off overrides:

```bash
# Method 1: Using KAM_UI_LANGUAGE (recommended)
export KAM_UI_LANGUAGE=zh
kam build

# Method 2: Using KAM_LANG (alternative)
export KAM_LANG=zh-CN
kam build

# One-time override for a single command
KAM_UI_LANGUAGE=zh kam build
```

**Supported values:**
- `zh`, `zh-CN`, `zh_CN` → Chinese (Simplified)
- `en`, `en-US`, `en_US` → English

### Setting Language via Config File

For persistent language settings, use the `kam config` command or edit the config file directly.

#### Using `kam config` Command

```bash
# Set global language (stored in ~/.kam/config.toml)
kam config --global set ui.language zh

# Or use the simplified key
kam config --global set language zh

# Set project-level language (stored in ./.kam/config.toml)
kam config set ui.language zh

# Verify the setting
kam config --global get ui.language
```

#### Editing Config File Directly

You can also edit the config file manually:

**Global config** (`~/.kam/config.toml`):
```toml
[ui]
language = "zh"

# Or simply:
language = "zh"
```

**Project-level config** (`./.kam/config.toml`):
```toml
[ui]
language = "zh"
```

**Note:** The `ui.language` key is preferred, but `language` is also supported for backward compatibility.

### System Locale Detection

If no environment variable or config file setting is found, Kam will attempt to detect the system locale using the `sys-locale` crate (if the feature is enabled). This requires the `sys-locale` feature to be enabled in the build.

### LANG Environment Variable Fallback

If system locale detection is not available, Kam falls back to checking the `LANG` environment variable:

```bash
export LANG=zh_CN.UTF-8
kam build
```

### Default Language

If none of the above methods provide a language setting, Kam defaults to **English**.

### Examples

#### Example 1: Set Global Language

```bash
# Set Chinese as the default language for all projects
kam config --global set ui.language zh

# Verify
kam config --global get ui.language
# Output: "zh"

# Now all kam commands will use Chinese
kam build
kam init my_module
```

#### Example 2: Override for Single Command

```bash
# Temporarily use Chinese for one command
KAM_UI_LANGUAGE=zh kam build

# Next command will use the default (from config or system)
kam init my_module
```

#### Example 3: Project-Specific Language

```bash
# Set language for current project only
cd my_project
kam config set ui.language en

# This project uses English, others use global/default
kam build
```

### Troubleshooting

#### Language Not Changing

If the language doesn't change as expected:

1. **Check environment variables:**
   ```bash
   echo $KAM_UI_LANGUAGE
   echo $KAM_LANG
   ```

2. **Check config file:**
   ```bash
   kam config --global list
   kam config list
   ```

3. **Verify the language value:**
   - Use `zh` or `zh-CN` for Chinese
   - Use `en` or `en-US` for English
   - Case-insensitive, but recommended to use lowercase

#### Reset to Default

To reset to default (English):

```bash
# Remove from global config
kam config --global unset ui.language
kam config --global unset language

# Remove from project config
kam config unset ui.language
kam config unset language

# Or unset environment variables
unset KAM_UI_LANGUAGE
unset KAM_LANG
```

---

## 中文

### 概述

Kam 提供了一个轻量级的国际化（i18n）系统，支持多种语言的 CLI 消息显示。语言检测遵循优先级顺序，允许您在不同级别覆盖语言设置。

### 支持的语言

- **英文**: `en`, `en-US`, `en_US`
- **简体中文**: `zh`, `zh-CN`, `zh_CN`

### 语言检测优先级

Kam 按以下顺序检测语言（优先级从高到低）：

1. **环境变量**（最高优先级）
2. **配置文件**（推荐用于持久化设置）
3. **系统语言环境**（如果可用则自动检测）
4. **LANG 环境变量**（后备方案）
5. **默认值**（如果以上都未设置，则使用英文）

### 通过环境变量设置语言

环境变量具有最高优先级，适合快速临时覆盖：

```bash
# 方法 1：使用 KAM_UI_LANGUAGE（推荐）
export KAM_UI_LANGUAGE=zh
kam build

# 方法 2：使用 KAM_LANG（替代方案）
export KAM_LANG=zh-CN
kam build

# 单次命令临时覆盖
KAM_UI_LANGUAGE=zh kam build
```

**支持的值：**
- `zh`, `zh-CN`, `zh_CN` → 简体中文
- `en`, `en-US`, `en_US` → 英文

### 通过配置文件设置语言

对于持久化的语言设置，请使用 `kam config` 命令或直接编辑配置文件。

#### 使用 `kam config` 命令

```bash
# 设置全局语言（存储在 ~/.kam/config.toml）
kam config --global set ui.language zh

# 或使用简化的键
kam config --global set language zh

# 设置项目级语言（存储在 ./.kam/config.toml）
kam config set ui.language zh

# 验证设置
kam config --global get ui.language
```

#### 直接编辑配置文件

您也可以手动编辑配置文件：

**全局配置** (`~/.kam/config.toml`):
```toml
[ui]
language = "zh"

# 或简单地：
language = "zh"
```

**项目级配置** (`./.kam/config.toml`):
```toml
[ui]
language = "zh"
```

**注意：** 推荐使用 `ui.language` 键，但为了向后兼容，也支持 `language` 键。

### 系统语言环境检测

如果未找到环境变量或配置文件设置，Kam 将尝试使用 `sys-locale` crate 检测系统语言环境（如果启用了该功能）。这需要在构建时启用 `sys-locale` feature。

### LANG 环境变量后备方案

如果系统语言环境检测不可用，Kam 会回退到检查 `LANG` 环境变量：

```bash
export LANG=zh_CN.UTF-8
kam build
```

### 默认语言

如果以上方法都未提供语言设置，Kam 默认使用**英文**。

### 示例

#### 示例 1：设置全局语言

```bash
# 将所有项目的默认语言设置为中文
kam config --global set ui.language zh

# 验证
kam config --global get ui.language
# 输出: "zh"

# 现在所有 kam 命令都将使用中文
kam build
kam init my_module
```

#### 示例 2：单次命令覆盖

```bash
# 临时为单个命令使用中文
KAM_UI_LANGUAGE=zh kam build

# 下一个命令将使用默认值（来自配置或系统）
kam init my_module
```

#### 示例 3：项目特定语言

```bash
# 仅为当前项目设置语言
cd my_project
kam config set ui.language en

# 此项目使用英文，其他项目使用全局/默认值
kam build
```

### 故障排除

#### 语言未更改

如果语言未按预期更改：

1. **检查环境变量：**
   ```bash
   echo $KAM_UI_LANGUAGE
   echo $KAM_LANG
   ```

2. **检查配置文件：**
   ```bash
   kam config --global list
   kam config list
   ```

3. **验证语言值：**
   - 使用 `zh` 或 `zh-CN` 表示中文
   - 使用 `en` 或 `en-US` 表示英文
   - 不区分大小写，但建议使用小写

#### 重置为默认值

要重置为默认值（英文）：

```bash
# 从全局配置中移除
kam config --global unset ui.language
kam config --global unset language

# 从项目配置中移除
kam config unset ui.language
kam config unset language

# 或取消设置环境变量
unset KAM_UI_LANGUAGE
unset KAM_LANG
```

### 技术细节

Kam 的国际化系统在 `src/i18n.rs` 中实现。它使用简单的键值映射来翻译常见的 CLI 消息。如果某个字符串没有翻译映射，将返回原始字符串，允许逐步国际化而无需立即修改所有调用点。

语言检测在程序启动时（`main()` 函数中）通过调用 `kam::i18n::init()` 进行初始化。
