@optima-chat/optima-agent 0.1.0

package/.claude/skills/commerce-i18n/SKILL.md

@@ -0,0 +1,460 @@
+---
+name: commerce-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
+
+国际化模块，用于管理商品、变体、集合、商户和首页的多语言翻译。
+
+## 典型场景 (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
+```
+
+## 卓越标准 (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 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` - 删除首页翻译
+
+## 详细示例 (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
+- **语言代码格式**：必须使用BCP 47格式（如 en-US），不能使用短代码（如 en）
+- **变体翻译参数**：使用 `--variant-id`（不是 `--product-id`）
+- **变体规格翻译**：`variant-attributes-translations` 格式需要同时翻译规格键和值
+- **商户翻译**：商户是单例，不需要指定ID
+- **首页区块翻译**：用于前端展示的多语言标题和描述
+- **规格翻译自动聚合**：主商品的 `variant_attributes_translations` 会自动从变体聚合，无需手动设置
+- **命令帮助**：使用 `commerce i18n <command> --help` 查看详细参数