从零造一个国际化文案提取 Skill：硬编码字符串秒变多语言资源

i18n-extract/
├── SKILL.md              # 入口：元数据 + 注入扫描结果 + 任务指令
├── scripts/
│   └── extract.py        # 文案扫描脚本（被注入执行，不进上下文）
└── reference.md          # key 命名规范、各 i18n 库接入要点（按需读）

mkdir -p ~/.claude/skills/i18n-extract/scripts
cd ~/.claude/skills/i18n-extract

#!/usr/bin/env python3
"""extract.py — 扫描前端源码里硬编码的用户可见文案。
用法: python3 extract.py <文件或目录> [--ext js,ts,jsx,tsx,vue]
输出: JSON 数组，每项含 file / line / text / key
"""
import argparse, json, os, re, sys

CJK = re.compile(r'[\u4e00-\u9fff]')
STR       = re.compile(r"""(['"])((?:\\.|(?!\1).)*)\1""")
TEMPLATE  = re.compile(r'`((?:\\.|[^`])*)`')
JSX_TEXT  = re.compile(r'>([^<>{}]+)<')
NOISE = re.compile(
    r'\b(import|from|require|console|http|url|src|href|className|key|type|name)\s*[:=]',
    re.I)

def keyify(text: str):
    s = re.sub(r'[^\w\u4e00-\u9fff]+', '_', text).strip('_').lower()
    parts = [p for p in parts if p][:6] if False else [p for p in s.split('_') if p][:6]
    return parts[0] + ''.join(p.capitalize() for p in parts[1:]) if parts else None

def looks_user_facing(text: str) -> bool:
    if len(text) < 2:
        return False
    if CJK.search(text):
        return True
    # 长英文短语（≥2 个空格分隔的词、含字母）也视为候选文案
    words = [w for w in text.split() if re.search(r'[A-Za-z]', w)]
    return len(words) >= 2 and len(text) >= 6

def scan_file(path, out):
    try:
        lines = open(path, encoding='utf-8').read().splitlines()
    except Exception:
        return
    for i, line in enumerate(lines, 1):
        if NOISE.search(line):
            continue
        for rx in (STR, TEMPLATE, JSX_TEXT):
            grp = 2 if rx is not JSX_TEXT else 1
            for m in rx.finditer(line):
                text = m.group(grp).strip()
                if looks_user_facing(text):
                    k = keyify(text)
                    if k:
                        out.append({"file": path, "line": i, "text": text, "key": k})

def walk(root, exts):
    for dp, dn, fn in os.walk(root):
        dn[:] = [d for d in dn if d not in {'node_modules', 'dist', 'build', '.git'}]
        for f in fn:
            if any(f.endswith('.' + e) for e in exts):
                yield os.path.join(dp, f)

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument('target')
    ap.add_argument('--ext', default='js,ts,jsx,tsx,vue')
    a = ap.parse_args()
    exts = [e.strip() for e in a.ext.split(',')]
    found = []
    if os.path.isdir(a.target):
        for f in walk(a.target, exts):
            scan_file(f, found)
    else:
        scan_file(a.target, found)
    seen, uniq = set(), []
    for f in found:                       # 同文案去重
        if f['text'] in seen:
            continue
        seen.add(f['text']); uniq.append(f)
    print(json.dumps(uniq, ensure_ascii=False, indent=2))

if __name__ == '__main__':
    main()

# 准备一个最小样本
mkdir -p /tmp/demo && cat > /tmp/demo/Login.jsx <<'EOF'
import React from 'react';
export const Login = ({user}) => (
  <div className="card">
    <h1>欢迎回来</h1>
    <p>请输入您的账号信息，{user.name}</p>
    <button>登录系统</button>
    <button>忘记密码？</button>
  </div>
);
EOF

python3 ~/.claude/skills/i18n-extract/scripts/extract.py /tmp/demo

[
  { "file": "/tmp/demo/Login.jsx", "line": 4, "text": "欢迎回来", "key": "欢迎回来" },
  { "file": "/tmp/demo/Login.jsx", "line": 5, "text": "请输入您的账号信息，{user.name}", "key": "请输入您的账号信息" },
  { "file": "/tmp/demo/Login.jsx", "line": 6, "text": "登录系统", "key": "登录系统" },
  { "file": "/tmp/demo/Login.jsx", "line": 7, "text": "忘记密码？", "key": "忘记密码" }
]

---
name: i18n-extract
description: 提取前端源码中硬编码的用户可见文案并生成国际化键值与改造计划。当用户提到"国际化""i18n""多语言""提取文案""hardcoded string""把中文抽成 key""vue-i18n/i18next 接入"时使用。
when_to_use: 用户想把 JSX/TSX/Vue/模板里的中文字符串或长英文短语抽成 t() 调用和翻译资源文件时触发。
paths: "**/*.{js,ts,jsx,tsx,vue}"
argument-hint: "[扫描目录或文件]"
arguments: [target]
allowed-tools: Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/extract.py *) Read Edit Glob Grep
---

## 当前扫描结果

!`python3 ${CLAUDE_SKILL_DIR}/scripts/extract.py "$target" 2>/dev/null || echo '[]'`

## 任务

你是国际化重构专家。基于上面的 JSON 扫描结果：

1. **校验去误报**：逐条审阅 text，剔除控制台日志、调试文本、纯技术标识。保留真正面向用户的文案。
2. **设计 key**：按页面/模块分组，驼峰命名（如 `login.welcomeTitle`、`login.enterAccountInfo`）。脚本给的 `key` 仅供启发。
3. **产出资源文件**：生成 `src/locales/zh-CN.json` 与 `src/locales/en-US.json` 草稿——中文值用原文，英文值先给占位 `{TODO}`。
4. **改造清单**：列出需把字面量替换为 `t('key')` 的 `文件:行号 → key` 映射，并标注项目使用的 i18n 库。

若扫描结果为空，说明未发现候选文案，建议用户检查 `--ext` 后缀或目标目录。

## 规则

- 模板插值（如 `${name}`、`{user.name}`）保留为占位：`欢迎，{name}`，资源文件用对应库的占位语法。
- 重复文案只建一个 key，全项目复用。
- 多词纯英文短语视为待翻译文案；单字/单词技术词（`isLoading`、`button`）视为代码标识，跳过。
- 用 Glob/Grep 确认项目 i18n 库（查 `package.json` 是否含 i18next/vue-i18n/@formatjs），资源目录以现状为准。
- 详细 key 命名规范与各库接入差异见 [reference.md](reference.md)，需要时再读。

# i18n key 命名规范与库接入要点

## 命名
- 小驼峰，按 域.页面.用途 分层：`auth.login.rememberMe`、`cart.empty.hint`。
- 动词/状态用动词原形：`save`、`saving`、`saved`。
- 含插值统一用单大括号占位：`共 {count} 条`。

## 库差异速查
- i18next：`t('key', { count })`，占位 `{{count}}`，资源挂在 `i18n.init({ resources })`。
- vue-i18n：模板里 `{{ $t('key') }}`，组合式 `const { t } = useI18n()`。
- @formatjs (react-intl)：`<FormattedMessage id="key" values={{count}}/>`，占位 `{count}`，需提取消息编译。

claude

/i18n-extract /tmp/demo

帮我把 src/components 里的硬编码中文抽成 i18n

context: fork
agent: Explore

!`mkdir -p logs && python3 ${CLAUDE_SKILL_DIR}/scripts/extract.py "$target" | tee logs/i18n-${CLAUDE_SESSION_ID}.json`

my-ui/
├ package.json          # 含 react、未含 i18next
└ src/
  ├ Button.tsx          # <button>提交</button>
  ├ Modal.tsx           # title="确认删除？"  confirmText="确定"
  └ pages/Order.tsx     # 共 {total} 笔订单

flowchart TD
    A["用户: /i18n-extract src"] --> B["Claude Code 匹配 Skill"]
    B --> C["读取 SKILL.md frontmatter"]
    C --> D{"满足 paths 触发条件?"}
    D -- 否 --> Z["不自动加载"]
    D -- 是 --> E["解析参数 \$target"]
    E --> F["动态注入: 执行 extract.py"]
    F --> G["脚本输出 JSON 原位替换进正文"]
    G --> H["模型读到的已是现成扫描结果"]
    H --> I["模型校验去误报"]
    I --> J["设计 i18n key + 生成资源文件草稿"]
    J --> K["产出 文件:行号 改造清单"]
    K --> L{"用户确认改造?"}
    L -- 是 --> M["Edit 逐处替换为 t() 调用"]
    L -- 否 --> N["结束, 输出草稿"]
    M --> O["完成"]

    subgraph 渐进式披露三层
      S1["SKILL.md 入口<br/>常驻"]
      S2["extract.py 脚本<br/>执行, 不进上下文"]
      S3["reference.md 详尽规范<br/>按需读"]
    end