From 8971d3653c2e910aba472f598a0f8f90a352e95a Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Tue, 16 Dec 2025 22:05:00 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0=E4=B8=AD=E6=96=87?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=B9=B6=E6=B7=BB=E5=8A=A0=20l10n=20?= =?UTF-8?q?=E5=B7=A5=E5=85=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 28 ++++---- i18n/zh/documents/README.md | 4 +- i18n/zh/prompts/README.md | 12 ++-- i18n/zh/skills/README.md | 26 +++---- libs/external/l10n-tool/README.md | 34 +++++++++ libs/external/l10n-tool/requirements.txt | 1 + libs/external/l10n-tool/translate.py | 90 ++++++++++++++++++++++++ 7 files changed, 161 insertions(+), 34 deletions(-) create mode 100644 libs/external/l10n-tool/README.md create mode 100644 libs/external/l10n-tool/requirements.txt create mode 100755 libs/external/l10n-tool/translate.py diff --git a/AGENTS.md b/AGENTS.md index 9e88ae0..279f16b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ - `make help`：列出所有 Make 目标，是新人快速上手的入口。 - `make lint`：使用 `markdownlint-cli` 校验全仓库 Markdown，一旦新增文档请先跑通（需本地 Node/npm 环境，可用 `npm install -g markdownlint-cli` 安装）。 - `make build` / `make test` / `make clean`：目前为占位，落地具体实现后务必更新脚本和说明；建议在 `Makefile` 旁补充注释并保持幂等，避免修改全局状态。 -- 提示词转换：进入 `i18n/zh/prompts/prompts-library/` 后执行 `python main.py` 按交互提示进行转换，运行前请确认虚拟环境、依赖与输出目录，并在完成后检查生成 Markdown 是否符合 lint 规则。 +- 提示词转换：进入 `libs/external/prompts-library/` 后执行 `python main.py` 按交互提示进行转换，运行前请确认虚拟环境、依赖与输出目录，并在完成后检查生成 Markdown 是否符合 lint 规则。 ## Coding Style & Naming Conventions - 文字层：文档、注释、日志使用中文；代码符号（函数 / 变量 / 模块）统一英文且语义直白，避免晦涩缩写。 @@ -35,7 +35,7 @@ - 外部依赖来源记录在 `libs/external/` 目录下，增减依赖时同步维护，保持可追溯；引入第三方脚本需标明许可证与来源。 ## Architecture Overview & Workflow -- 工作流倡导「规划 → 上下文固定 → 分步实现 → 自测 → 复盘」，对应资产分别存放在 `i18n/zh/documents/`、`i18n/zh/i18n/zh/prompts/`、`libs/` 与备份脚本中。保持单向数据流和清晰责任边界可以避免后期维护成本激增。 +- 工作流倡导「规划 → 上下文固定 → 分步实现 → 自测 → 复盘」，对应资产分别存放在 `i18n/zh/documents/`、`i18n/zh/prompts/`、`libs/` 与备份脚本中。保持单向数据流和清晰责任边界可以避免后期维护成本激增。 - 设计决策与目录结构更新后，请同步修订本文件与相关文档，确保团队共享同一真相源，减少口头约定与隐式规则。 --- @@ -71,8 +71,8 @@ bash backups/一键备份.sh ## Architecture & Structure ### Core Directories -- **`i18n/zh/prompts/`**: The core asset. A massive, well-organized library of prompts. - - `coding_i18n/zh/prompts/`, `system_i18n/zh/prompts/`, `user_i18n/zh/prompts/` +- **`i18n/zh/prompts/`**: The core asset. A massive, well-organized library of prompts. + - `coding_prompts/`, `system_prompts/`, `user_prompts/`, `meta_prompts/` - **`i18n/zh/skills/`**: A modular library of skills for the AI, providing domain-specific knowledge for various tools like `ccxt`, `postgresql`, `telegram-dev`, etc. - **`i18n/zh/documents/`**: The project's knowledge base, containing methodology, principles, and guides. @@ -119,11 +119,12 @@ When modifying this repository: ## 主要功能与工作流程 (Key Features & Workflow) -1. **AI 提示词库 (`i18n/zh/prompts/`):** - * 一个极其庞大和精细分类的提示词集合，是项目的核心资产。 - * `coding_i18n/zh/prompts/`: 专注于编程和代码生成的提示词。 - * `system_i18n/zh/prompts/`: 用于设定 AI 行为和思维框架的系统级提示词。 - * `user_i18n/zh/prompts/`: 用户自定义或常用的提示词。 +1. **AI 提示词库 (`i18n/zh/prompts/`):** + * 一个极其庞大和精细分类的提示词集合，是项目的核心资产。 + * `coding_prompts/`: 专注于编程和代码生成的提示词。 + * `system_prompts/`: 用于设定 AI 行为和思维框架的系统级提示词。 + * `user_prompts/`: 用户自定义或常用的提示词。 + * `meta_prompts/`: 元提示词与提示工程辅助。 2. **提示词库管理工具 (`libs/external/prompts-library/`):** * 提供 Python 工具 (`main.py`)，用于在 Excel 工作簿 (`prompt_excel/`) 和 Markdown 文档 (`prompt_docs/`) 之间进行提示词的相互转换。 @@ -178,10 +179,11 @@ When modifying this repository: │ ├── my-nvim/ # 个人 Neovim 配置。 │ └── XHS-image-to-PDF-conversion/ # 小红书图片转 PDF 工具。 │ -├── i18n/zh/prompts/ # 核心资产：AI 提示词库。 -│ ├── coding_i18n/zh/prompts/ # 编程与代码生成相关提示词。 -│ ├── system_i18n/zh/prompts/ # AI 系统级提示词。 -│ └── user_i18n/zh/prompts/ # 用户自定义提示词。 +├── i18n/zh/prompts/ # 核心资产：AI 提示词库。 +│ ├── coding_prompts/ # 编程与代码生成相关提示词。 +│ ├── system_prompts/ # AI 系统级提示词（含 CLAUDE 版本目录）。 +│ ├── user_prompts/ # 用户自定义提示词。 +│ └── meta_prompts/ # 元提示词与提示工程辅助。 │ └── i18n/zh/skills/ # 模块化技能库。 ├── ccxt/ # CCXT 加密货币交易库技能。 diff --git a/i18n/zh/documents/README.md b/i18n/zh/documents/README.md index f5d29d9..469dcbc 100644 --- a/i18n/zh/documents/README.md +++ b/i18n/zh/documents/README.md @@ -1,11 +1,11 @@ # 📖 文档库 (Documents) -`documents/` 目录汇总项目的流程文档、架构说明、开发经验与最佳实践，是理解方法论与协作规则的首选入口。 +`i18n/zh/documents/` 目录汇总项目的流程文档、架构说明、开发经验与最佳实践，是理解方法论与协作规则的首选入口。 ## 目录结构 ``` -documents/ +i18n/zh/documents/ ├── README.md │ ├── Methodology and Principles/ diff --git a/i18n/zh/prompts/README.md b/i18n/zh/prompts/README.md index ff2eafc..4f245c1 100644 --- a/i18n/zh/prompts/README.md +++ b/i18n/zh/prompts/README.md @@ -1,6 +1,6 @@ # 💡 AI 提示词库 (Prompts) -`prompts/` 存放本仓库的提示词资产：用 **系统提示词** 约束 AI 的边界与品味，用 **任务提示词** 驱动「需求澄清 → 计划 → 执行 → 复盘」的开发流水线。 +`i18n/zh/prompts/` 存放本仓库的提示词资产：用 **系统提示词** 约束 AI 的边界与品味，用 **任务提示词** 驱动「需求澄清 → 计划 → 执行 → 复盘」的开发流水线。 ## 推荐使用路径（从 0 到可控） @@ -11,7 +11,7 @@ ## 目录结构（以仓库真实目录为准） ``` -prompts/ +i18n/zh/prompts/ ├── README.md ├── coding_prompts/ # 编程/研发提示词（当前 41 个 .md） │ ├── index.md # 自动生成的索引与版本矩阵（请勿手改） @@ -37,7 +37,7 @@ prompts/ 系统提示词用于定义 **工作模式、代码品味、输出格式、安全边界**。目录采用版本化结构： -- 路径约定：`prompts/system_prompts/CLAUDE.md/<版本号>/CLAUDE.md` +- 路径约定：`i18n/zh/prompts/system_prompts/CLAUDE.md/<版本号>/CLAUDE.md` - 推荐版本： - `v8`：综合版，适合通用 Vibe Coding - `v10`：偏 Augment/上下文引擎的规范化约束 @@ -66,15 +66,15 @@ prompts/ ```bash # 查看一个任务提示词 -sed -n '1,160p' prompts/coding_prompts/标准化流程.md +sed -n '1,160p' i18n/zh/prompts/coding_prompts/标准化流程.md # 选定系统提示词版本（建议先备份你当前的 CLAUDE.md） -cp prompts/system_prompts/CLAUDE.md/10/CLAUDE.md ./CLAUDE.md +cp i18n/zh/prompts/system_prompts/CLAUDE.md/10/CLAUDE.md ./CLAUDE.md ``` ## 维护与批量管理（可选） -如果你需要 Excel ↔ Markdown 的批量维护能力，仓库内置了第三方工具：`libs/external/prompts-library/`。建议把它视为“提示词资产的生产工具”，而把 `prompts/` 视为“日常开发的精选集”。 +如果你需要 Excel ↔ Markdown 的批量维护能力，仓库内置了第三方工具：`libs/external/prompts-library/`。建议把它视为“提示词资产的生产工具”，而把 `i18n/zh/prompts/` 视为“日常开发的精选集”。 ## 相关资源 diff --git a/i18n/zh/skills/README.md b/i18n/zh/skills/README.md index 45b6514..beecdee 100644 --- a/i18n/zh/skills/README.md +++ b/i18n/zh/skills/README.md @@ -1,11 +1,11 @@ # 🎯 AI Skills 技能库 -`skills/` 目录存放 AI 技能（Skills），这些是比提示词更高级的能力封装，可以让 AI 在特定领域表现出专家级水平。当前包含 **14 个**专业技能。 +`i18n/zh/skills/` 目录存放 AI 技能（Skills），这些是比提示词更高级的能力封装，可以让 AI 在特定领域表现出专家级水平。当前包含 **14 个**专业技能。 ## 目录结构 ``` -skills/ +i18n/zh/skills/ ├── README.md # 本文件 │ ├── # === 元技能（核心） === @@ -118,23 +118,23 @@ skill-name/ ```bash # 查看元技能 -cat skills/claude-skills/SKILL.md +cat i18n/zh/skills/claude-skills/SKILL.md # 查看 PostgreSQL 技能（最详细） -cat skills/postgresql/SKILL.md +cat i18n/zh/skills/postgresql/SKILL.md # 查看 Telegram Bot 开发技能 -cat skills/telegram-dev/SKILL.md +cat i18n/zh/skills/telegram-dev/SKILL.md ``` ### 2. 复制到项目中使用 ```bash # 复制整个技能目录 -cp -r skills/postgresql/ ./my-project/ +cp -r i18n/zh/skills/postgresql/ ./my-project/ # 或只复制主文件到 CLAUDE.md -cp skills/postgresql/SKILL.md ./CLAUDE.md +cp i18n/zh/skills/postgresql/SKILL.md ./CLAUDE.md ``` ### 3. 结合 Claude Code 使用 @@ -145,8 +145,8 @@ cp skills/postgresql/SKILL.md ./CLAUDE.md # 项目规则 请参考以下技能文件： -@skills/postgresql/SKILL.md -@skills/telegram-dev/SKILL.md +@i18n/zh/skills/postgresql/SKILL.md +@i18n/zh/skills/telegram-dev/SKILL.md ``` ## 创建自定义 Skill @@ -154,12 +154,12 @@ cp skills/postgresql/SKILL.md ./CLAUDE.md ### 方法一：使用元技能生成（推荐） 1. 准备领域资料（文档、代码、规范） -2. 将资料和 `skills/claude-skills/SKILL.md` 一起提供给 AI +2. 将资料和 `i18n/zh/skills/claude-skills/SKILL.md` 一起提供给 AI 3. AI 会生成针对该领域的专用 Skill ```bash # 示例：让 AI 读取元技能后生成新技能 -cat skills/claude-skills/SKILL.md +cat i18n/zh/skills/claude-skills/SKILL.md # 然后告诉 AI：请根据这个元技能，为 [你的领域] 生成一个新的 SKILL.md ``` @@ -167,10 +167,10 @@ cat skills/claude-skills/SKILL.md ```bash # 创建技能目录 -mkdir -p skills/my-skill/{assets,scripts,references} +mkdir -p i18n/zh/skills/my-skill/{assets,scripts,references} # 创建主文件 -cat > skills/my-skill/SKILL.md << 'EOF' +cat > i18n/zh/skills/my-skill/SKILL.md << 'EOF' # My Skill ## 概述 diff --git a/libs/external/l10n-tool/README.md b/libs/external/l10n-tool/README.md new file mode 100644 index 0000000..35c1b36 --- /dev/null +++ b/libs/external/l10n-tool/README.md @@ -0,0 +1,34 @@ +# l10n-tool + +轻量级多语言翻译脚本，定位：先用机器翻译批量落地，再由 AI/人工逐行润色。 + +## 特性 +- 保护 Markdown 代码块，不误翻译代码 +- 命令行一条跑完，便于批处理 +- 依赖轻：`deep-translator`（封装 Google 翻译） + +## 安装 +```bash +pip install -r requirements.txt +``` + +## 使用示例 +```bash +# 将中文 README 翻译到英文 +python translate.py --input ../../i18n/zh/README.md --output ../../i18n/en/README.md --src-lang zh --tgt-lang en --overwrite + +# 批量翻译 prompts，可在外部脚本中循环调用 +``` + +## 建议流程（快 ⇒ 精） +1) 机器翻译初稿：用本工具覆盖生成各语言版本。 +2) AI 校润：对关键文档/提示词逐行复核，重点检查术语一致性与人称语气。 +3) 人工抽检：挑核心页面人工对比源文，修正 AI 可能的误译。 + +## 语言代码参考 +- 常用：zh, en, es, fr, de, ru, pt, ar, hi, ja, ko, he, it, tr, nl, pl, id, vi, th, fa, uk, bn, ta, ur, ms, sw, ha +- 更多代码可查 ISO 639-1。 + +## 注意 +- 若需更高质量，可替换为官方 Google Cloud Translate / DeepL API，只需改写 `translate_blocks` 中的 translator 初始化逻辑。 +- 如遇免费翻译频率限制，可分批或加重试/代理配置。 diff --git a/libs/external/l10n-tool/requirements.txt b/libs/external/l10n-tool/requirements.txt new file mode 100644 index 0000000..f4bcfbb --- /dev/null +++ b/libs/external/l10n-tool/requirements.txt @@ -0,0 +1 @@ +deep-translator>=1.11.4 diff --git a/libs/external/l10n-tool/translate.py b/libs/external/l10n-tool/translate.py new file mode 100755 index 0000000..4d958ca --- /dev/null +++ b/libs/external/l10n-tool/translate.py @@ -0,0 +1,90 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +轻量级批量翻译工具：将 Markdown/文本从一种语言翻译到另一种语言。 +默认使用 deep-translator 封装的 Google Translator，自带简单的代码块保护。 +用法示例： + python translate.py --input ../../i18n/zh/README.md --src-lang zh --tgt-lang en --output ../../i18n/en/README.md +""" + +import argparse +import os +import sys +from typing import List + +try: + from deep_translator import GoogleTranslator +except ImportError as exc: # pragma: no cover - 运行前请安装依赖 + sys.stderr.write("[错误] 缺少依赖 deep-translator，请先 `pip install -r requirements.txt`\n") + raise + + +def translate_blocks(lines: List[str], src: str, tgt: str) -> List[str]: + """逐段翻译，保持代码块原样，减少上下文丢失。""" + translated: List[str] = [] + in_code = False + buffer: List[str] = [] + translator = GoogleTranslator(source=src, target=tgt) + + def flush_buffer(): + if not buffer: + return + text = "\n".join(buffer) + try: + result = translator.translate(text) + except Exception as exc: # pragma: no cover + raise RuntimeError(f"翻译失败: {exc}") from exc + translated.extend(result.split("\n")) + buffer.clear() + + for line in lines: + if line.strip().startswith("```"): + flush_buffer() + in_code = not in_code + translated.append(line) + continue + if in_code: + translated.append(line) + continue + # 空行作为段落分割，先刷新再保留空行 + if not line.strip(): + flush_buffer() + translated.append(line) + continue + buffer.append(line) + + flush_buffer() + return translated + + +def main() -> int: + parser = argparse.ArgumentParser(description="批量翻译文本/Markdown，保护代码块") + parser.add_argument("--input", required=True, help="源文件路径") + parser.add_argument("--output", required=True, help="目标文件路径") + parser.add_argument("--src-lang", required=True, help="源语言代码，如 zh") + parser.add_argument("--tgt-lang", required=True, help="目标语言代码，如 en") + parser.add_argument("--overwrite", action="store_true", help="允许覆盖已有输出文件") + args = parser.parse_args() + + if not os.path.isfile(args.input): + sys.stderr.write(f"[错误] 源文件不存在: {args.input}\n") + return 1 + if os.path.exists(args.output) and not args.overwrite: + sys.stderr.write(f"[错误] 目标文件已存在，加 --overwrite 才会覆盖: {args.output}\n") + return 1 + + with open(args.input, "r", encoding="utf-8") as f: + lines = f.read().splitlines() + + translated = translate_blocks(lines, args.src_lang, args.tgt_lang) + + os.makedirs(os.path.dirname(args.output), exist_ok=True) + with open(args.output, "w", encoding="utf-8") as f: + f.write("\n".join(translated) + "\n") + + print(f"[完成] {args.input} -> {args.output} ({args.src_lang} -> {args.tgt_lang})") + return 0 + + +if __name__ == "__main__": # pragma: no cover + sys.exit(main())