企业官网建设流程全解析

prompts.chat 书籍多语言翻译实战：以 book-translation Skill 为核心的 MDX 内容、JSON 词条与交互组件三层翻译体系

【免费下载链接】prompts.chatf.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete privacy.项目地址: https://gitcode.com/GitHub_Trending/aw/prompts.chat

本篇指南基于 prompts.chat 仓库中的.windsurf/skills/book-translation/SKILL.md展开，完整讲解如何为交互式提示词书籍《The Interactive Book of Prompting》新增一种语言的翻译：从以完整译文为底稿的 MDX 文件复制策略，到messages/{locale}.json中book段落的词条翻译，再到交互式演示所依赖的src/components/book/elements/locales/本地化数据文件的创建与注册，最后用scripts/check-translations.js脚本完成翻译完整性的自动化校验。读完本文，你可以独立完成一个新语言的端到端接入，并理解每一层翻译产物在运行时的真实消费链路。

一、翻译体系总览：一本书、三层翻译产物

book-translationSkill 的核心前提是把书籍翻译拆成两个必须同时交付的部分（原文档 Overview 一节）：

1. MDX 内容文件——完整的章节正文，位于src/content/book/{locale}/；
2. JSON 翻译键——界面文案、章节标题与描述，位于messages/{locale}.json的"book"段落。

Skill 原文档称全书包含25 章、分 7 个 Part。从仓库实际文件看，src/content/book/下除00a-preface.mdx到25-agents-and-skills.mdx外还包含14a-loop-engineering.mdx，即 29 个章节文件；messages/en.json中book.chapters恰好也是29 个条目（脚本核对结果），说明 Skill 文档中的"25 章"是早期章节数，实际以messages/en.json与src/content/book/目录清单为准。七个 Part 的键名在en.json中确认为：

"parts": { "introduction": "Introduction", "foundations": "Foundations", "techniques": "Techniques", "advanced": "Advanced Strategies", "bestPractices": "Best Practices", "useCases": "Use Cases", "conclusion": "Conclusion" }

在 MDX 与 JSON 之外，仓库源码揭示了 Skill 文档重点强调的第三层（Step 3 中的 "Book Elements Locales"）：交互式演示组件（温度示例、token 预测、tokenizer、提示词构建器、链式演示、框架演练等）并不走messages/*.json，而是从一个独立的、强类型的本地化数据包取数。其结构定义在 types.ts，顶层LocaleData接口包含 25 个字段，覆盖 Skill 文档列出的全部数据域：

• 演示数据：temperatureExamples、tokenPrediction、embeddingWords、capabilities、sampleConversation、strategies、contextBlocks、scenarios、steps、tokenizer、builderFields、chainTypes；
• 导航与原理：bookParts、principles；
• 安全章节：jailbreakExamples；
• 多模态演示：imagePromptOptions、imageCategoryLabels、videoPromptOptions、videoCategoryLabels；
• 链式演示：validationDemo、fallbackDemo、contentPipelineDemo；
• 练习与框架：exercises（填空、清单、调试器三类）、frameworks（CRISPE / BREAK / RTF）。

理解这三层产物及其对应的消费方（MDX 渲染、i18n 词条、组件内嵌数据），是正确执行翻译流程的基础。

二、前置准备：确认目标语言码与现有产物

开始翻译前，Skill 要求先确定三件事：

• 目标语言码（如de、fr、es、ja、ko、zh）；
• 检查messages/目录下是否已有该语言的 JSON 文件；
• 检查src/content/book/{locale}/目录是否已存在。

从当前仓库看，messages/下已有 17 个语言文件（ar、az、de、el、en、es、fa、fr、he、it、ja、ko、nl、pt、ru、tr、zh），src/content/book/下除英文根目录外已有 16 个语言子目录，src/components/book/elements/locales/下则已有 17 个数据文件（en、tr、az加 14 个后补语言），三者已对齐。若三者都缺失，即是从零开始接入的完整场景；若只有部分存在，则按缺失的那一层补齐即可——这正是把翻译任务拆成三层的实用价值。

三、Step 1：以现有完整译文为底稿批量复制

Skill 给出的核心策略是：不从英文重新翻译，而是复制一份已完成的翻译作为起点。原文档推荐以土耳其语（tr）为基准并说明理由：土耳其语与许多语言句子结构相近、JSX/React 组件已保留完好、文件结构已经就位，因此只需要翻译散文部分而不必重建结构。原文给出的命令：

mkdir -p src/content/book/{locale} cp -r src/content/book/*.mdx src/content/book/{locale}/ cp src/components/book/elements/locales/en.ts src/components/book/elements/locales/{locale}.ts

这里有一个值得注意的细节：bash 命令实际是从英文根目录src/content/book/*.mdx复制 MDX，而locales数据文件则从en.ts复制——也就是说命令与"复制土耳其语文件夹"的标题并不完全一致。同一篇 Skill 末尾的 "Reference: English Translation" 一节进一步确认：英文是官方基准模板（base template），src/content/book/*.mdx是复制源，messages/en.json的book段落是结构参考。两种说法并存可以理解为：结构上以英文为基准，而"为什么土耳其语适合当参照"指的是翻译措辞与结构相似度上的经验提示。实际操作时，建议以英文 MDX 为复制源、以messages/en.json为键结构基准，这与仓库现状（各语言 MDX 均与英文根目录文件一一对应）一致。

复制完成后，Skill 用醒目的警告标出不可跳过的注册步骤——在 index.ts 中登记新语言：

1. 添加导入：import {locale} from "./{locale}";
2. 加入locales对象：{locale},
3. 加入命名导出：export { en, tr, az, {locale} };

对照当前 index.ts 的真实实现，这一流程已演化为 17 个语言的注册表：

const locales: Record<string, LocaleData> = { en, tr, az, fr, de, es, it, pt, ja, zh, ko, ar, nl, ru, el, fa, he, }; export function getLocaleData(locale: string): LocaleData { return locales[locale] || locales.en; // 缺失时回退英文 }

注意getLocaleData的英文回退语义：未注册的语言不会报错，而是静默回退到英文数据。这解释了为什么 Skill 把注册步骤标为 REQUIRED——漏注册时页面能打开、但新语言的交互式演示会整片显示英文，且不会有任何报错提示，只能靠人工逐页比对发现。

四、Step 2：逐文件翻译 MDX 章节正文

Skill 要求对src/content/book/{locale}/中的每个文件逐篇处理。原文档给出的章节顺序表（含 25 章标题）与仓库src/content/book/实际文件核对后如下（表中补充了原文档未列出的00a/00b/00c三篇前置章节、14a-loop-engineering与根目录文件总数 29 的差异，以仓库文件名为准）：

MDX 翻译的五条硬性规则（原文档 "MDX Translation Guidelines"）：

1. 保留全部 JSX/React 组件——<div>、<img>、className等一律不改；
2. 保留代码块——代码示例保持英文（变量名、关键字不译）；
3. 翻译散文——标题、段落、列表项；
4. 保留 Markdown 语法——##、**bold**、*italic*、links；
5. 保留组件导入——文件顶部的任何import语句原样保留。

这些规则之所以关键，从源码结构看，书籍章节通过 Fumadocs 式的内容路由按"语言子目录 + 相同文件名"解析：同一 locale 目录下只要出现一个文件缺失或文件名改动，对应的/book/{locale}/{slug}路由就会 404。以中文为例，01-understanding-ai-models.mdx 与根目录英文版本逐篇对应、行数相当（约 300 行），正文为中文而内部组件与代码块保持英文，正是上述五条规则的实际产物。

五、Step 3：翻译 messages JSON 的 book 段落

messages/{locale}.json中需要翻译的是顶层"book"对象。以 en.json 实测，该段落除 Skill 文档点名的四组之外，还包含一系列导航与介绍性词条，完整键列表为：

title、donate、subtitle、metaTitle、metaDescription、interactiveGuideBy、authorIntro、bookDescription、whatYouWillLearn、highlights、bookStructure、structure、startReading、skipToChapter1、continuousUpdate、partOfProject、kidsSection、chapter、tableOfContents、awesomeChatGPTPrompts、search、bookmark、parts、chapters、chapterDescriptions、interactive、printTitle、printSubtitle、downloadPdf。

按 Skill 文档划分的四组重点键区如下。

5.1 书籍元数据（title / subtitle / meta）

"book": { "title": "The Interactive Book of Prompting", "subtitle": "An Interactive Guide to Crafting Clear and Effective Prompts", "metaTitle": "...", "metaDescription": "..." }

metaTitle/metaDescription影响书籍首页的 SEO 元信息，翻译时应按目标语言的用户搜索习惯重写，而不是直译。

5.2 章节标题（book.chapters）与章节描述（book.chapterDescriptions）

"chapters": { "00a-preface": "Preface", "00b-history": "History", "00c-introduction": "Introduction", "...": "..." }, "chapterDescriptions": { "00a-preface": "A personal note from the author", "00b-history": "The story of Awesome ChatGPT Prompts", "...": "..." }

这两组以章节 slug 为键，键名不可翻译，只需翻译值；条目数应与src/content/book/{locale}/下的文件数一一对应（当前为 29）。

5.3 Part 名称（book.parts）与演示示例（book.interactive.demoExamples）

book.parts的 7 个键如上文总览所示。book.interactive.demoExamples用于本地化交互式演示的示例文本，en.json中实际包含 4 个子键：tokenPrediction、tokenizer、temperature、fewShot，例如：

"demoExamples": { "tokenPrediction": { "tokens": ["The", " capital", " of", " France", " is", " Paris", "."], "fullText": "The capital of France is Paris." }, "temperature": { "prompt": "What is the capital of France?", "...": "..." } }

翻译这类示例时要保证tokens数组拼接后与fullText一致（含词间空格），因为它们直接驱动逐 token 动画渲染；temperature的各级示例则应模拟"低温度收敛、高温度发散"的语义差异，而不是四段同义句。

5.4 界面词条（book.interactive.* / book.chapter.* / book.search.*）

翻译全部交互组件的标签与导航字符串，例如startReading、skipToChapter1、tableOfContents、search、bookmark、downloadPdf等，覆盖书籍首页、侧边栏、目录与搜索等界面位置。

5.5 书籍元素本地化数据文件（REQUIRED）

Skill 文档用 "DO NOT SKIP THIS STEP" 警告的第三层：翻译src/components/book/elements/locales/{locale}.ts。需要翻译的数据域包括温度示例、token 预测、embedding 词表、能力清单、示例对话、摘要策略、tokenizer 样例、构建器字段、链式类型、框架（CRISPE、BREAK、RTF）、练习题、图像/视频提示词选项与各类验证演示——即LocaleData的全部 25 个字段，完整字段结构见 types.ts。

以土耳其语 tr.ts 为例（该文件约 405 行），temperatureExamples演示了数据翻译的语义要求：低温度三句几乎相同，高温度三句则明显风格化发散；tokenPrediction.tokens按目标语言真实分词（土耳其语按词内空格与后缀拆分），predictions中的概率分布也按语言习惯重排。这说明该层翻译不是逐串替换，而要对演示语义做等价重构。

完成后必须回到 index.ts 完成三处注册（导入、locales对象、命名导出），并确认新文件通过LocaleData类型约束——类型定义保证了字段缺失会在编译期暴露，这是该层最可靠的自检手段。

六、Step 4：用 check-translations.js 校验翻译完整性

Skill 规定的验证流程三步：

# 1. 运行翻译完整性检查 node scripts/check-translations.js # 2. 启动开发服务器 npm run dev # 3. 访问 /book 并切换到目标语言，逐页验证内容加载

check-translations.js 的工作机制值得细读，它回答"新语言翻译齐了没有"这一问题：

1. 读取messages/en.json作为源，用flattenKeys把嵌套对象展平成点号路径键集合（数组不作为键，整体视为叶子值）；
2. 遍历messages/下除en.json外的全部语言文件，同样展平；
3. 双向比对：missing= 英文有而该语言缺的键（会连带打印英文原值，便于直接翻译），extra= 该语言有而英文没有的键（通常是笔误或多余键）；
4. 汇总输出各语言缺失数量与总数，全部通过时打印 "All translation files are complete!"。

需要注意该脚本只校验messages/*.json这一层，不覆盖MDX 目录与locales/*.ts数据文件的完整性。后两者的核对方式是：src/content/book/{locale}/文件数与根目录英文一致（29 个）、locales/{locale}.ts通过LocaleData类型检查并在index.ts中注册（否则会被静默回退英文）。把脚本校验、类型校验与/book/{locale}页面走查三件事都做完，才算一次完整的新语言接入。

七、推荐工作流与翻译质量准则

Skill 末尾给出两条对工作方式与质量的约束，均值得保留为执行纪律。

推荐工作流（Recommended Workflow）：

1. 复制src/content/book/*.mdx到src/content/book/{locale}/；
2. 把messages/en.json的"book"段复制到messages/{locale}.json，并且分多个 agentic 会话分批翻译，而不是一次性完成——原文档的理由是单会话 token 上限可能装不下全部词条；
3. 逐文件编辑，完成英文到目标语言的翻译；
4. 全程保持 JSX 组件、代码块与 Markdown 语法原样。

质量准则（Quality Guidelines）：

• 一致性：全书使用统一术语（例如 "prompt" 必须始终译成同一个词）；
• 技术词保留：AI、ChatGPT、API等可以保留英文原文；
• 文化适配：示例内容在合适处替换为目标受众更熟悉的场景；
• 自然优先：优先保证译文读起来自然，而非逐字直译。

结合仓库现状，这几条准则的实际压力点在于：book.chapterDescriptions与demoExamples中的示例句数量最大、最容易在长篇翻译中发生术语漂移，而locales/{locale}.ts里 25 个数据域的重复短语（如步骤名、按钮文案）又天然要求跨文件一致。以en/tr/az为参照稿、逐数据域而非逐文件翻译，是降低漂移的最直接做法。

八、小结：三层产物与三道校验

把本文与仓库源码对齐后的完整接入清单如下，可作为验收 checklist：

第三层的注册遗漏是唯一会被getLocaleData静默回退英文掩盖的环节，因此人工走查/book页面在新语言下各演示组件（温度、token 预测、构建器、链式演示、练习题）的显示语言，是不可省略的最后一步。完成上述三层翻译与三道校验后，新语言即与仓库现有 16 种语言子目录同等可用。

【免费下载链接】prompts.chatf.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete privacy.项目地址: https://gitcode.com/GitHub_Trending/aw/prompts.chat