---
name: i18n
description: Internationalization and translation management. Add multilingual translations for products, variants, collections, merchant info, homepage sections. Use when user needs to translate content, manage multiple languages, or configure i18n settings.
---

# Commerce CLI - Internationalization

国际化模块，用于管理商品、变体、集合、商户和首页的多语言翻译。

## 核心策略（重要）

**English (en-US) is the base/default language of the Optima platform.**

- 平台默认语言是英文，商品主表内容对应英文用户看到的内容
- 中文和其他语言通过 `i18n` 命令作为翻译添加（存储在翻译表中）
- 未翻译的内容自动回退到主表内容（英文）

**语言选择规则**：
- 用户同时提供中英文内容 → **英文作为主表内容，中文通过 i18n 添加翻译**
- 用户只提供中文内容 → 用中文创建商品，但建议同时添加英文翻译
- 用户要求"国际化"或"多语言" → 确保英文内容在主表，其他语言通过 i18n 添加

**推荐的国际化流程**：
```bash
# 1. 用英文创建商品（作为基础语言存入主表）
commerce product create --name "Cotton T-Shirt" --price 99 --description "100% cotton, breathable and comfortable"

# 2. 添加中文翻译
commerce i18n product create --product-id prod_123 --lang zh-CN --name "纯棉T恤" --description "100% 纯棉，舒适透气"

# 3. 根据需要添加其他语言
commerce i18n product create --product-id prod_123 --lang ja-JP --name "コットンTシャツ" --description "..."
```

**避免**：用中文创建商品后再加英文翻译 —— 这会导致主表存储中文，英文用户（无翻译覆盖时）看到中文内容。

## 典型场景 (Typical Scenarios)

### 场景决策表

| 用户需求 | 推荐命令 | 关键注意点 |
|---------|---------|-----------|
| 新增语言 | `i18n merchant create` → 集合 → 商品 | 按优先级翻译，先商户、集合、热门商品 |
| 翻译商品 | `i18n product create` | 名称和描述必填，SEO关键词要本地化 |
| 翻译变体 | `i18n variant create` | 使用variant-id（不是product-id），包含规格翻译 |
| 翻译集合 | `i18n collection create` | 名称要简洁，描述突出价值 |
| 翻译首页区块 | `i18n homepage set` | 用于前端展示，标题≤30字，描述≤100字 |
| 更新翻译 | `i18n * update` | 原文变更后及时同步更新 |

### 场景1: 新语言启用

**典型需求**：店铺扩展到日本市场，需要添加日语支持

**推荐流程**：
1. **翻译商户信息** - `commerce i18n merchant create --lang ja-JP` 设置店铺名称、描述
2. **翻译核心集合** - 翻译首页展示的3-5个主要集合
3. **翻译热门商品** - 优先翻译销量前20的商品
4. **翻译首页区块** - 翻译轮播图标题、精选区块标题
5. **翻译变体规格** - 为有变体的商品添加规格翻译
6. **批量翻译其他商品** - 逐步补充完整商品库翻译
7. **验证完整性** - 检查关键页面是否所有内容已翻译

```bash
# 1. 翻译商户信息
commerce i18n merchant create --lang ja-JP --name "ファッションストア" --description "..."

# 2. 翻译核心集合
commerce i18n collection create --collection-id coll_featured --lang ja-JP --name "おすすめ商品"

# 3. 翻译热门商品
commerce i18n product create --product-id prod_hot_1 --lang ja-JP --name "..." --description "..."
```

### 场景2: 商品翻译

**典型需求**：为新上架商品添加多语言版本

**推荐做法**：先翻译商品基本信息，再翻译变体规格

```bash
# 1. 翻译商品基本信息
commerce i18n product create \
  --product-id prod_123 \
  --lang en-US \
  --name "Handmade Ceramic Mug" \
  --description "Beautiful handcrafted ceramic mug for everyday use"

# 2. 如果有变体，再翻译变体
commerce i18n variant create --variant-id var_456 --lang en-US \
  --name "Red Ceramic Mug (Small)" \
  --variant-attributes-translations '{...}'
```

### 场景3: 变体规格翻译

**典型需求**：为T恤商品的颜色和尺寸规格添加英文翻译

**关键点**：主商品的 `variant_attributes_translations` 会自动从变体聚合，只需翻译变体即可。

```bash
# 1. 创建主商品翻译（不需要翻译variant_attributes_translations）
commerce i18n product create --product-id prod_123 --lang en-US --name "T-Shirt"

# 2. 翻译所有变体（包括规格）
commerce i18n variant create --variant-id var_1 --lang en-US \
  --name "Red T-Shirt (Small)" \
  --variant-attributes-translations '{
    "颜色": {"key_translation": "Color", "value_translation": {"红色": "Red"}},
    "尺寸": {"key_translation": "Size", "value_translation": {"S": "Small"}}
  }'

# 3. 主商品会自动聚合变体的规格翻译
commerce i18n product get --product-id prod_123 --lang en-US
```

### 场景4: 批量翻译

**典型需求**：为所有商品添加新语言翻译

**推荐策略**：按优先级分批翻译，先重要内容后次要内容

```bash
# 1. 先翻译商户信息
commerce i18n merchant create --lang es-ES --name "Tienda de Moda" --description "..."

# 2. 获取热门商品列表（按销量排序）
commerce product list --sort-by sales --limit 20

# 3. 优先翻译热门商品
commerce i18n product create --product-id prod_hot_1 --lang es-ES --name "..." --description "..."
commerce i18n product create --product-id prod_hot_2 --lang es-ES --name "..." --description "..."

# 4. 翻译核心集合
commerce i18n collection create --collection-id coll_featured --lang es-ES --name "Productos Destacados"

# 5. 最后批量翻译其他商品
for product_id in $(commerce product list --json | jq -r '.[].id'); do
  commerce i18n product create --product-id $product_id --lang es-ES --name "..."
done
```

### 场景5: 翻译更新

**典型需求**：原文商品名称变更，需要同步更新翻译

```bash
# 查看现有翻译
commerce i18n product list --product-id prod_123

# 更新特定语言翻译
commerce i18n product update \
  --product-id prod_123 \
  --lang en-US \
  --name "Updated Product Name"
```

### 场景6: 首页区块翻译

**典型需求**：为首页精选区块添加多语言标题和描述

```bash
# 中文
commerce i18n homepage set \
  --section-id section_123 \
  --lang zh-CN \
  --title "精选商品" \
  --description "查看我们最受欢迎的产品"

# 英文
commerce i18n homepage set \
  --section-id section_123 \
  --lang en-US \
  --title "Featured Products" \
  --description "Discover our most popular items"

# 查看区块的所有翻译
commerce i18n homepage list --section-id section_123
```

### 场景7: 店铺政策翻译

```bash
# 翻译退货政策
commerce i18n shop-policy set --policy-type returns --lang zh-CN --title "退货政策" --content "# 退货政策\n\n..."

# 翻译隐私政策
commerce i18n shop-policy set --policy-type privacy --lang ja-JP --title "プライバシーポリシー" --content "# ..."
```

### 场景8: 店铺关于页面翻译

```bash
# 翻译关于页面
commerce i18n shop-about set --lang zh-CN --about-content "# 我们的故事\n\n..."

# 翻译联系页面补充内容
commerce i18n shop-about set --lang ja-JP --contact-content "# お問い合わせ\n\n..."
```

## 卓越标准 (Excellence Standards)

### 翻译质量维度
- **翻译完整性**: 核心字段100%翻译（商品名、描述、规格）
- **语言准确性**: 使用母语审校，避免机翻错误
- **本地化适配**: 考虑文化差异，调整表达方式（如日期格式、货币符号）
- **SEO优化**: 标题包含目标语言关键词，长度符合搜索引擎要求
- **更新及时性**: 原文变更后24小时内同步更新翻译

### 翻译管理原则
- **语言代码规范**: 使用BCP 47格式（en-US, zh-CN），不用短代码（en, zh）
- **优先级排序**: 先翻译商品和集合，再翻译变体细节
- **一致性检查**: 同一术语在不同场景保持一致（如"Size"统一译为"サイズ"）
- **变体规格翻译**: 先翻译规格键（如"颜色"→"Color"），再翻译规格值（如"红色"→"Red"）
- **占位符策略**: 未翻译的内容回退到默认语言，不显示空白

### 语言选择策略

**目标市场推荐**：
- **北美市场** - en-US（必须）
- **欧洲市场** - es-ES（西班牙语覆盖拉美）
- **亚洲市场** - ja-JP（日本）, vi-VN（越南）, zh-CN（中国大陆）
- **全球电商** - en-US + es-ES + zh-CN（覆盖70%全球用户）

**翻译投入建议**：
- 小店铺：先支持1-2种主要语言
- 中型店铺：支持3-5种语言，覆盖核心市场
- 大型店铺：支持5种以上语言，专人维护翻译质量

### 上线前质量检查清单

**必查项**：
- [ ] 商户信息已翻译（名称、描述）
- [ ] 首页所有区块标题已翻译
- [ ] 核心集合已翻译（至少5个）
- [ ] 热门商品已翻译（至少20个）
- [ ] 变体规格翻译格式正确
- [ ] 无机翻痕迹（如直译、语序错误）
- [ ] 术语一致性（如Size统一译法）
- [ ] 移动端显示正常（无溢出、截断）

## 常见问题 (Common Problems)

### ❌ 问题1: 批量翻译无优先级规划

**错误做法**：
```bash
# 不规划优先级，随机翻译所有商品
for product_id in $(commerce product list --json | jq -r '.[].id'); do
  commerce i18n product create --product-id $product_id --lang ja-JP --name "..."
done
```

**问题**：
- 浪费时间在低价值商品上
- 用户访问热门商品时仍然看到未翻译内容
- 翻译成本高但用户体验提升不明显

✅ **正确做法**：按优先级分批翻译（见"场景4: 批量翻译"）

### ❌ 问题2: 使用错误的参数名称

**错误做法**：
```bash
# 为变体创建翻译时使用 --product-id
commerce i18n product create --product-id var_456 --lang en-US --name "..."
```

**问题**：
- 变体ID不是商品ID，会导致找不到实体
- 变体规格翻译会丢失

✅ **正确做法**：
```bash
# 使用 i18n variant 命令和 --variant-id 参数
commerce i18n variant create --variant-id var_456 --lang en-US \
  --name "Red Mug (Small)" \
  --variant-attributes-translations '{...}'
```

### ❌ 问题3: 手动维护主商品的规格翻译

**错误做法**：
```bash
# 为主商品手动设置 variant_attributes_translations
commerce i18n product create --product-id prod_123 --lang en-US \
  --name "T-Shirt" \
  --variant-attributes-translations '{...}'  # 不需要手动设置
```

**问题**：
- 主商品的规格翻译会自动从变体聚合
- 手动设置会被自动聚合覆盖
- 浪费时间维护不必要的数据

✅ **正确做法**：只翻译变体，主商品会自动聚合（见"场景3: 变体规格翻译"）

### ❌ 问题4: 使用短语言代码

**错误做法**：
```bash
commerce i18n product create --product-id prod_123 --lang en --name "..."
commerce i18n product create --product-id prod_123 --lang zh --name "..."
```

**问题**：
- 不符合BCP 47标准
- 无法区分地区变体（如 en-US vs en-GB，zh-CN vs zh-TW）
- 可能导致API错误

✅ **正确做法**：
```bash
# 使用完整的BCP 47语言代码
commerce i18n product create --product-id prod_123 --lang en-US --name "..."
commerce i18n product create --product-id prod_123 --lang zh-CN --name "..."
```

### ❌ 问题5: 机翻痕迹明显

**错误做法**：
```bash
# 直接使用机器翻译结果，不做人工审校
commerce i18n product create --product-id prod_123 --lang ja-JP \
  --name "手工芸陶器マグカップ" \  # 直译，不自然
  --description "毎日の使用のための美しい手作り陶器マグカップ"  # 语序不自然
```

**问题**：
- 日语语序不符合习惯
- 用词不地道
- 影响用户信任度

✅ **正确做法**：
```bash
# 经过母语审校的自然表达
commerce i18n product create --product-id prod_123 --lang ja-JP \
  --name "手作り陶器マグカップ" \  # 自然顺序
  --description "日常使いにぴったりな、美しい手作りの陶器マグカップです"  # 符合日语表达习惯
```

### ❌ 问题6: 术语不一致

**错误做法**：
```bash
# 同一个规格键在不同商品中翻译不一致
commerce i18n variant create --variant-id var_1 --lang ja-JP \
  --variant-attributes-translations '{"尺寸": {"key_translation": "サイズ", ...}}'

commerce i18n variant create --variant-id var_2 --lang ja-JP \
  --variant-attributes-translations '{"尺寸": {"key_translation": "大きさ", ...}}'  # 不一致
```

**问题**：
- 用户体验不一致
- 筛选功能可能失效
- 显得不专业

✅ **正确做法**：建立术语表，保持一致
```bash
# 所有商品的"尺寸"统一翻译为"サイズ"
commerce i18n variant create --variant-id var_1 --lang ja-JP \
  --variant-attributes-translations '{"尺寸": {"key_translation": "サイズ", ...}}'

commerce i18n variant create --variant-id var_2 --lang ja-JP \
  --variant-attributes-translations '{"尺寸": {"key_translation": "サイズ", ...}}'
```

## 命令参考 (Commands Reference)

### 自然语言映射

当用户说：
- "给商品添加中文翻译" → `commerce i18n product create --product-id XX --lang zh-CN`
- "翻译商品变体" → `commerce i18n variant create --variant-id XX --lang YY`
- "翻译集合信息" → `commerce i18n collection create --collection-id XX --lang YY`
- "设置商户多语言信息" → `commerce i18n merchant create --lang XX`
- "翻译首页区块" → `commerce i18n homepage set --section-id XX --lang YY`
- "翻译店铺政策" → `commerce i18n shop-policy set --policy-type XX --lang YY`
- "翻译关于页面" → `commerce i18n shop-about set --lang XX`

### 商品翻译

- `commerce i18n product create` - 创建商品翻译
- `commerce i18n product list` - 查看商品翻译列表
- `commerce i18n product get` - 查看单个翻译
- `commerce i18n product update` - 更新翻译
- `commerce i18n product delete` - 删除翻译

### 变体翻译

- `commerce i18n variant create` - 创建变体翻译
- `commerce i18n variant list` - 查看变体翻译
- `commerce i18n variant update` - 更新变体翻译
- `commerce i18n variant delete` - 删除变体翻译

### 集合翻译

- `commerce i18n collection create` - 创建集合翻译
- `commerce i18n collection list` - 查看集合翻译
- `commerce i18n collection update` - 更新集合翻译
- `commerce i18n collection delete` - 删除集合翻译

### 商户翻译

- `commerce i18n merchant create` - 创建商户翻译
- `commerce i18n merchant list` - 查看商户翻译
- `commerce i18n merchant update` - 更新商户翻译
- `commerce i18n merchant delete` - 删除商户翻译

### 首页翻译

- `commerce i18n homepage set` - 设置首页区块翻译
- `commerce i18n homepage list` - 查看首页翻译
- `commerce i18n homepage delete` - 删除首页翻译

### 店铺政策翻译

- `commerce i18n shop-policy set` - 设置店铺政策翻译

### 店铺关于页面翻译

- `commerce i18n shop-about set` - 设置店铺关于页面翻译

## 详细示例 (Detailed Examples)

### 商品翻译示例

```bash
# 用户说："给商品prod_123添加中文翻译"
commerce i18n product create \
  --product-id prod_123 \
  --lang zh-CN \
  --name "手工陶瓷杯" \
  --description "精美的手工制作陶瓷杯，适合日常使用"
```

### 变体翻译示例

```bash
# 用户说："给变体var_456添加日语翻译，包括规格翻译"
commerce i18n variant create \
  --variant-id var_456 \
  --lang ja-JP \
  --name "セラミックマグ（赤・小）" \
  --variant-attributes-translations '{
    "颜色": {
      "key_translation": "色",
      "value_translation": {"红色": "赤"}
    },
    "尺寸": {
      "key_translation": "サイズ",
      "value_translation": {"S": "小"}
    }
  }'
```

### 集合翻译示例

```bash
# 用户说："给summer-sale集合添加西班牙语翻译"
commerce i18n collection create \
  --collection-id coll_789 \
  --lang es-ES \
  --name "Promoción de Verano" \
  --description "Grandes ofertas para el verano"
```

### 商户翻译示例

```bash
# 用户说："添加商户的英文翻译"
commerce i18n merchant create \
  --lang en-US \
  --name "Fashion Store" \
  --description "Your premium fashion destination"
```

### 首页区块翻译示例

```bash
# 用户说："给首页精选区块添加中英文标题"
# 中文
commerce i18n homepage set \
  --section-id section_123 \
  --lang zh-CN \
  --title "精选商品" \
  --description "查看我们最受欢迎的产品"

# 英文
commerce i18n homepage set \
  --section-id section_123 \
  --lang en-US \
  --title "Featured Products" \
  --description "Discover our most popular items"
```

### 批量翻译示例

```bash
# 用户说："把所有商品翻译成日语"
# 1. 获取商品列表
commerce product list --limit 100

# 2. 逐个添加翻译
commerce i18n product create --product-id prod_1 --lang ja-JP --name "..."
commerce i18n product create --product-id prod_2 --lang ja-JP --name "..."
```

## 重要提示 (Important Notes)

- **支持的语言**：en-US, es-ES, ja-JP, vi-VN, zh-CN, zh-HK, zh-TW
- **语言代码格式**：必须使用BCP 47格式（如 en-US），不能使用短代码（如 en）
- **变体翻译参数**：使用 `--variant-id`（不是 `--product-id`）
- **变体规格翻译**：`variant-attributes-translations` 格式需要同时翻译规格键和值
- **商户翻译**：商户是单例，不需要指定ID
- **首页区块翻译**：用于前端展示的多语言标题和描述
- **规格翻译自动聚合**：主商品的 `variant_attributes_translations` 会自动从变体聚合，无需手动设置
- **命令帮助**：使用 `commerce i18n <command> --help` 查看详细参数
