---
title: 国际化与语言
---

# 国际化与语言

ZCF 提供完善的国际化（i18n）支持，允许您灵活配置 CLI 界面语言、AI 输出语言和模板语言，满足不同场景的语言需求。

## 语言配置层级

ZCF 的语言系统分为三个独立但相关的层级：

1. **CLI 语言**：ZCF 工具本身的界面语言
2. **AI 输出语言**：AI 助手回复的语言
3. **模板语言**：工作流模板和提示词的语言

这三个层级可以独立配置，满足各种混合场景需求。

## CLI 语言

CLI 语言控制 ZCF 命令行工具的界面显示语言。

### 支持的语言

- `zh-CN`：简体中文
- `en`：英文

### 语言优先级

CLI 语言按照以下优先级确定：

1. 命令行参数 `--all-lang` 或 `--lang`
2. 配置文件中的 `preferredLang`
3. 交互式选择
4. 系统默认（`en`）

### 设置 CLI 语言

```bash
# 通过命令行参数
npx zcf --lang zh-CN
npx zcf init --lang zh-CN

# 通过统一语言参数（推荐）
npx zcf --all-lang zh-CN

# 在主菜单中切换
npx zcf
# 输入 0 切换语言

# 配置文件位置
cat ~/.ufomiao/zcf/config.toml | grep preferredLang
```

### 语言切换实现

语言切换通过以下函数实现：

- `changeLanguage`：切换 i18n 语言
- `resolveAndSwitchLanguage`：解析并切换语言（考虑优先级）

## AI 输出语言

AI 输出语言控制 AI 助手回复和生成内容使用的语言，可以与 CLI 语言不同。

### 支持的语言选项

- `zh-CN`：中文输出
- `en`：英文输出
- `custom`：自定义语言指令

### 设置 AI 输出语言

```bash
# 初始化时设置
npx zcf init --ai-output-lang zh-CN

# 或使用统一参数
npx zcf init --all-lang zh-CN

# 在主菜单中配置
npx zcf
# 选择 6 (配置 AI 记忆与输出风格)
# 然后选择 AI 输出语言
```

### 自定义语言指令

使用 `custom` 选项可以输入自定义语言指令：

```bash
npx zcf init --ai-output-lang custom
# 然后输入：使用日语回复，保持专业和礼貌的语调
```

自定义指令会写入 `CLAUDE.md` 或 `AGENTS.md`，影响 AI 的输出语言和风格。

### AI 输出语言配置位置

- **Claude Code**：`~/.claude/CLAUDE.md` 中的语言指令
- **Codex**：`~/.codex/AGENTS.md` 中的语言指令

## 模板语言

模板语言控制工作流模板、提示词和系统提示的语言版本。

### 支持的语言

- `zh-CN`：中文模板
- `en`：英文模板

### 模板语言独立性

模板语言与 CLI 语言相互独立，可以灵活组合：

```bash
# 中文界面 + 英文模板（适合需要英文文档的场景）
npx zcf init --lang zh-CN --config-lang en

# 英文界面 + 中文模板（适合国际化团队）
npx zcf init --lang en --config-lang zh-CN

# 统一语言（推荐大多数场景）
npx zcf init --all-lang zh-CN
```

### 设置模板语言

```bash
# 初始化时设置
npx zcf init --config-lang zh-CN

# 更新时设置
npx zcf update --config-lang zh-CN

# 或使用统一参数
npx zcf init --all-lang zh-CN
```

### 模板语言解析

模板语言通过 `resolveTemplateLanguage` 函数确定：

1. 命令行参数 `--config-lang`
2. 配置文件中的 `templateLang`
3. CLI 当前语言（如果未指定）
4. 系统默认（`en`）

## Codex 语言配置

切换到 Codex 后，语言配置规则相同：

```bash
# Codex 初始化，使用中文
npx zcf init -T codex --all-lang zh-CN

# 在 Codex 菜单中切换语言
# Codex 模式下的菜单会提供语言切换选项
```

## 使用场景

### 场景 1：中文环境（推荐）

适合大多数中文用户：

```bash
npx zcf init --all-lang zh-CN
```

结果：
- CLI 界面：中文
- AI 输出：中文
- 模板文件：中文

### 场景 2：中文界面 + 英文代码

适合需要英文代码注释的项目：

```bash
npx zcf init --lang zh-CN --ai-output-lang en --config-lang zh-CN
```

结果：
- CLI 界面：中文
- AI 输出：英文（代码注释和文档）
- 模板文件：中文

### 场景 3：国际化团队

适合需要英文文档的国际化团队：

```bash
npx zcf init --lang en --config-lang en --ai-output-lang en
```

结果：
- CLI 界面：英文
- AI 输出：英文
- 模板文件：英文

### 场景 4：混合配置

灵活组合满足特定需求：

```bash
# 中文界面、中文模板、自定义 AI 输出
npx zcf init \
  --lang zh-CN \
  --config-lang zh-CN \
  --ai-output-lang custom
# 输入：使用中文回复，代码注释使用英文
```

## 最佳实践

### 1. 团队统一配置

在团队协作中，建议统一语言配置：

```bash
# 团队统一使用中文
npx zcf init --all-lang zh-CN

# 或团队统一使用英文
npx zcf init --all-lang en
```

这样可以确保：
- 团队成员体验一致
- 文档格式统一
- 协作更顺畅

### 2. 项目特定配置

不同项目可能有不同需求：

```bash
# 开源项目：使用英文
npx zcf init --all-lang en

# 内部项目：使用中文
npx zcf init --all-lang zh-CN

# 混合项目：中文界面 + 英文输出
npx zcf init --lang zh-CN --ai-output-lang en
```

### 3. 文档多语言

如果需要多语言文档：

```bash
# 1. 先用中文生成完整文档
npx zcf init --all-lang zh-CN
# 完成功能开发，生成中文文档

# 2. 切换到英文，更新文档
npx zcf update --config-lang en
# 生成英文版本的文档

# 3. 使用 GitBook 多语言功能管理
```

### 4. 配置文件管理

语言配置保存在 ZCF 全局配置中：

```bash
# 查看当前配置
cat ~/.ufomiao/zcf/config.toml

# 配置文件字段
# preferredLang: CLI 语言偏好
# templateLang: 模板语言偏好
# aiOutputLang: AI 输出语言偏好
```

### 5. 脚本化配置

在自动化脚本中明确指定语言：

```bash
#!/bin/bash
# 部署脚本

# 明确指定所有语言参数
npx zcf init -s \
  --all-lang zh-CN \
  --provider 302ai \
  --api-key "$API_KEY"
```

## 故障排除

### 语言配置不生效

如果语言配置没有生效：

```bash
# 1. 检查配置文件
cat ~/.ufomiao/zcf/config.toml | grep -E "preferredLang|templateLang|aiOutputLang"

# 2. 重新初始化并明确指定
npx zcf init --all-lang zh-CN

# 3. 检查环境变量（如果有设置）
echo $LANG
```

### 模板语言与预期不符

如果模板语言与预期不符：

```bash
# 1. 明确指定模板语言
npx zcf init --config-lang zh-CN

# 2. 更新现有配置
npx zcf update --config-lang zh-CN

# 3. 检查模板文件
ls -la ~/.claude/workflows/
# 查看模板文件的语言版本
```

### AI 输出语言不对

如果 AI 输出语言不正确：

```bash
# 1. 检查 CLAUDE.md 或 AGENTS.md
cat ~/.claude/CLAUDE.md | grep -i language
cat ~/.codex/AGENTS.md | grep -i language

# 2. 重新配置 AI 输出语言
npx zcf
# 选择 6 (配置 AI 记忆与输出风格)

# 3. 或直接编辑配置文件
vim ~/.claude/CLAUDE.md
# 添加语言指令
```

## 相关资源

- [配置管理](configuration.md) - 详细配置管理指南
- [模板系统](templates.md) - 模板语言和自定义
- [快速开始](../getting-started/installation.md) - 初始化流程

> 💡 **提示**：合理配置语言设置可以大大提高开发效率和团队协作体验。建议根据项目需求和团队情况选择合适的语言配置。大多数中文用户推荐使用 `--all-lang zh-CN` 获得最佳体验。