🚧 一些i18n的准备工作

Author: Gaubee

.gitignore

@@ -16,3 +16,5 @@ __pycache__
 package-lock.json
 pnpm-lock.yaml
 en.bak
+.env.local
+.env

docs/.vitepress/config.mts

@@ -46,7 +46,7 @@ export default defineConfig({
           );
         },
       }),
-    ] as any,
+    ] ,
   },
   head: [["link", { rel: "icon", type: "image/svg+xml", href: "/logo.svg" }]],
   themeConfig: {

docs/.vitepress/i18n/en.json

@@ -4,24 +4,32 @@
   "description": "dweb-browser开发者文档",
   "type": "module",
   "devDependencies": {
+    "@gaubee/util": "^0.21.0",
     "@plaoc/is-dweb": "^0.1.2",
     "@plaoc/plugins": "^1.1.1",
     "@plaoc/server": "^0.4.1",
-    "@shikijs/twoslash": "^1.27.0",
-    "@shikijs/vitepress-twoslash": "^1.26.2",
+    "@shikijs/twoslash": "^2.1.0",
+    "@shikijs/vitepress-twoslash": "^2.1.0",
+    "@std/cli": "npm:@jsr/std__cli@^1.0.11",
+    "@std/path": "npm:@jsr/std__path@^1.0.8",
     "@types/node": "^22.10.6",
     "autoprefixer": "^10.4.19",
+    "dotenv": "^16.4.7",
+    "front-matter": "^4.0.2",
     "gray-matter": "^4.0.3",
+    "import-meta-ponyfill": "^3.2.1",
+    "openai": "^4.80.1",
     "postcss": "^8.5.1",
     "sass": "^1.83.4",
-    "shiki": "^1.27.0",
+    "shiki": "^2.1.0",
     "tailwindcss": "^3.4.17",
     "unocss": "^65.4.0",
     "unplugin-vue-components": "^28.0.0",
-    "vite": "^6.0.7",
-    "vitepress": "^1.5.0",
+    "vite": "^6.0.11",
+    "vitepress": "^1.6.3",
     "vitepress-plugin-group-icons": "^1.3.4",
-    "vue": "^3.4.27"
+    "vue": "^3.4.27",
+    "zod": "^3.24.1"
   },
   "optionalDependencies": {
     "@rollup/rollup-linux-x64-gnu": "4.30.1"

package.json

@@ -0,0 +1,17 @@
+import { isGlob, globToRegExp } from "@std/path";
+export type I18nConfig = {
+  ignore?: Array<(path: string) => boolean>;
+};
+
+export const createI18nConfig = (options: {
+  ignore?: string[];
+}): I18nConfig => {
+  const ignore = options.ignore?.map((ignore) => {
+    if (isGlob(ignore)) {
+      const reg = globToRegExp(ignore);
+      return (path: string) => reg.test(path);
+    }
+    return (path: string) => path.includes(path);
+  });
+  return { ignore };
+};

scripts/config.ts

@@ -0,0 +1,77 @@
+import fs from "fs";
+import path from "path";
+import frontmatter from "front-matter";
+import { I18nConfig } from "./config.ts";
+
+export class FileProcessor {
+  constructor(private config: I18nConfig) {}
+
+  processMarkdown(content: string) {
+    const { attributes, body } = frontmatter(content);
+    const { ignoreBlocks, i11nBlocks } = this.parseComments(body);
+
+    return {
+      frontmatter: attributes,
+      content: body,
+      ignoreBlocks,
+      i11nBlocks,
+    };
+  }
+
+  processJson(content: string) {
+    const data = JSON.parse(content);
+    const ignoredKeys = new Set<string>();
+    const i11nKeys = new Map<string, string>();
+
+    for (const [key, value] of Object.entries(data)) {
+      if (key.startsWith("//")) {
+        if (Array.isArray(value) && value.includes("i18n-ignore")) {
+          ignoredKeys.add(key.replace("//", ""));
+        }
+        if (Array.isArray(value) && value.some((v) => v.startsWith("i11n:"))) {
+          const msg =
+            value.find((v) => v.startsWith("i11n:"))?.split(":")[1] || "";
+          i11nKeys.set(key.replace("//", ""), msg);
+        }
+      }
+    }
+
+    return { data, ignoredKeys, i11nKeys };
+  }
+
+  private parseComments(content: string) {
+    const ignoreRegex =
+      /<!-- i18n-ignore-start -->([\s\S]*?)<!-- i18n-ignore-end -->/g;
+    const i11nRegex = /<!-- i11n-start: (.*?) -->([\s\S]*?)<!-- i11n-end -->/g;
+
+    return {
+      ignoreBlocks: [...content.matchAll(ignoreRegex)],
+      i11nBlocks: [...content.matchAll(i11nRegex)],
+    };
+  }
+
+  walkDir(dir: string) {
+    const results: string[] = [];
+    const list = fs.readdirSync(dir);
+
+    list.forEach((file) => {
+      const fullPath = path.join(dir, file);
+      const stat = fs.statSync(fullPath);
+
+      if (this.config.ignore?.some((isIgnore) => isIgnore(fullPath))) return;
+
+      if (stat?.isDirectory()) {
+        results.push(...this.walkDir(fullPath));
+      } else if (this.isTargetFile(fullPath)) {
+        results.push(fullPath);
+      }
+    });
+
+    return results;
+  }
+
+  private isTargetFile(filePath: string) {
+    const ext = path.extname(filePath);
+    return [".md", ".json"].includes(ext);
+  }
+}

scripts/file-processor.ts

@@ -0,0 +1,99 @@
+import { execSync } from "child_process";
+
+interface GitConfig {
+  commitPrefix: string;
+  targetBranches: string[];
+}
+
+export class GitHelper {
+  constructor(private config: GitConfig) {}
+
+  commit(message: string, files: string[] = ["."]) {
+    const fullMessage = `${this.config.commitPrefix} ${message}`;
+    execSync(`git add ${files.join(" ")}`);
+    execSync(`git commit -m "${fullMessage}"`);
+  }
+
+  getTranslationLogs() {
+    const cmd = [
+      "git log",
+      `--grep='^${this.config.commitPrefix}' -E --invert-grep`,
+      '--pretty=format:"%h|%ad|%s"',
+      "--date=iso",
+      "--name-status",
+      ...this.config.targetBranches.map((b) => `origin/${b}`),
+    ].join(" ");
+
+    const output = execSync(cmd).toString();
+    return this.parseLogOutput(output);
+  }
+
+  private parseLogOutput(output: string) {
+    const commits: CommitChange[] = [];
+    let currentCommit: CommitChange | null = null;
+
+    output.split("\n").forEach((line) => {
+      if (line.startsWith('"')) {
+        const [hash, date, ...msgParts] = line.replace(/"/g, "").split("|");
+        currentCommit = {
+          hash,
+          date: new Date(date),
+          message: msgParts.join("|"),
+          changes: [],
+        };
+        commits.push(currentCommit);
+      } else if (currentCommit && line.trim()) {
+        const [type, path] = line.split("\t");
+        currentCommit.changes?.push({
+          type: this.normalizeChangeType(type),
+          date: currentCommit.date,
+          path: path.trim(),
+          diff: this.getLineDiff(path),
+        });
+      }
+    });
+
+    return commits.filter((c) => c.changes?.length);
+  }
+
+  private getLineDiff(path: string) {
+    try {
+      return execSync(`git diff -U0 ${path}`).toString();
+    } catch {
+      return "";
+    }
+  }
+
+  private normalizeChangeType(type: string): ChangeType {
+    const mapping: Record<string, ChangeType> = {
+      A: "file-add",
+      D: "file-delete",
+      M: "file-modify",
+      R: "file-rename",
+      C: "file-copy",
+    };
+    return mapping[type[0]] || "unknown";
+  }
+}
+
+export type ChangeType =
+  | "file-add"
+  | "file-delete"
+  | "file-modify"
+  | "file-rename"
+  | "file-copy"
+  | "unknown";
+
+export interface CommitChange {
+  hash: string;
+  date: Date;
+  message: string;
+  changes: FileChange[];
+}
+
+export interface FileChange {
+  type: ChangeType;
+  date: Date;
+  path: string;
+  diff: string;
+}

scripts/git-helper.ts

@@ -0,0 +1,72 @@
+import path from "node:path";
+import fs from "node:fs";
+import { CommitChange } from "./git-helper";
+import { FileProcessor } from "./file-processor";
+
+interface TranslationContext {
+  sourceLang: string;
+  targetLangs: string[];
+  priorityOrder: string[];
+  changes: CommitChange[];
+}
+
+class I18nCore {
+  async generateTranslationPrompt(
+    filePath: string,
+    context: TranslationContext
+  ) {
+    const { ext } = path.parse(filePath);
+    const processor = new FileProcessor(this.config);
+    const content = fs.readFileSync(filePath, "utf-8");
+
+    let parsed: any;
+    if (ext === ".md") {
+      parsed = processor.processMarkdown(content);
+    } else {
+      parsed = processor.processJson(content);
+    }
+
+    const historyPrompt = this.buildHistoryPrompt(filePath, context);
+    const instructionPrompt = this.buildInstructionPrompt(parsed);
+
+    return `
+        ${this.config.systemPrompt}
+        
+        ## Translation Task
+        ${historyPrompt}
+        
+        ## Content Structure
+        ${JSON.stringify(parsed, null, 2)}
+        
+        ## Special Instructions
+        ${instructionPrompt}
+        
+        Please output in ${this.config.outputFormat} format.
+      `;
+  }
+
+  private buildHistoryPrompt(filePath: string, context: TranslationContext) {
+    const relatedChanges = context.changes
+      .flatMap((c) => c.changes)
+      .filter((c) => c.path === filePath);
+
+    if (!relatedChanges.length) return "No recent changes detected.";
+
+    return `
+        Recent changes detected:
+        ${relatedChanges
+          .map(
+            (c) => `
+          - ${c.type} at ${c.date.toISOString()}
+          ${c.diff.split("\n").slice(0, 5).join("\n")}
+        `
+          )
+          .join("\n")}
+        
+        Please pay special attention to these changes and ensure:
+        1. Consistency across all language versions
+        2. Preserve manual modifications marked with i11n
+        3. Follow priority order: ${context.priorityOrder.join(" > ")}
+      `;
+  }
+}

scripts/i18n-core.ts

@@ -0,0 +1,34 @@
+协助我做一个针对 vitepress 的的 AI 翻译。
+我的思路大概是这样的，首先我会用代码遍历我的 vitepress 项目中的 docs 文件夹，找出其中的 md 文件和 json 文件。这些文件将会交给 AI 翻译。（母语使用中文）
+给 AI 翻译的时候，有两种情况，一种是，这是一个新文件，因此只有中文，所以提供给 AI 的时候，AI 就直接翻译出英文等其它配置好的语言。
+还有一种情况，是这个文件之前已经翻译过了，因此我们需要通过 git 命令，来查阅最后一次执行翻译指令的 commit-hash，对比现在的 commit-hash，将这个过程中的 changelog 提取出来（当然这需要排除掉 AI 翻译本身的提交，只针对人类的提交，这就意味着 AI 翻译的提交需要在 commit-message 中添加一些特定的消息标识，这样就能跳过 AI 翻译内容带来的困扰，只针对人类的提交，因为人类通常只会提交某一种或者少数的几种语言翻译）。于是这样就能知道，最后一次修改的是中文还是英文还是其它语言，根据每行变更的最后一次的修改，来将这些修改同步翻译到其它语言中。
+
+因此，在代码中，我需要解决这几个问题，首先，是关于 git 工具的封装。
+你需要协助我封装出一套 git 工具，如上文所述：
+
+1. commit 函数：这个 commit 函数能根据配置，附加上特定的标识作为前缀，比如我会习惯使用 git-emoji 来做标识
+2. loglist 函数：这个 loglist 函数能根据特定的前缀标识，找到最后一次具有相同标识的 commit（就是最后一次执行 AI 翻译提交的 comit），然后这次 commit 之后的 commit 罗列出来（就是后续人类提交的 commit），然后整理出是变动信息。比如说“行变动”、“行新增”、“行删除”、“文件新增”、“文件重命名”、“文件删除”等情况。以“行新增”为例，需要描述是哪一个文件、使用什么语言、哪一行代码变动了，变动前是什么，变动后是什么；再比如以新增文件为例，需要描述哪一个文件，使用说明语言，文件内容是什么。注意，这里是整理多次提交，因此我们需要将多次提交合并成一次提交来看待（我想 git 应该有相关的命令可以直接做到这个效果）。
+
+然后是翻译提示词的问题，通常情况下，我们需要尊重原文来进行翻译的。
+这里主要是关于多种语言同时输入的情况：
+因为人类是会对 AI 翻译过后的内容做出一些修改的，虽然 AI 可以对原文进行准确的翻译，不过一旦人类介入后，内容可能会发生一些改变，因此同时输入英文中文，AI 不能单纯地就把中文当作母本、把英文当作译本，而是要结合内容以及 loglist 来判断，到底有没有必要对内容内容进行修改。比如说我作为人类，在提交中文后，接着执行 AI 翻译代码，生成新的 commit 把英文的内容也提交了，然后人类对 AI 的英文再做出了一些修改再做了一次提交，此时再将双语内容提交给 AI，这时候 AI 其实就应该把英文和中文都当是人类审核过的内容，都应该当作原文来对待。此时 AI 的目标是减少不同语言之间的含义差距，同时也应该尊重人类的修改。
+另外就是，人类在执行 AI 翻译的时候，会告诉 AI 自己的熟悉的语言顺序，比如说：`['中文、繁体中文', '英文']`。那么就意味着，AI 在根据 loglist 进行多语言进行翻译的过程中，可以先翻译 人类已知的语言，然后等人类审核通过后，来为其它语言做翻译，这样可能会更加准确。（这也就意味着 AI 翻译可以分两种模式：一种是全量翻译模式（一次新处理所有需要进行翻译的语言），一种是增量翻译模式（先处理人类熟悉的语言，然后再根据审核修改过的结果，对其余内容做翻译）。
+
+在有就是有些情况下，人类需要介入翻译，这里列举三种情况：
+
+1. 有些翻译只出现在某一种语言中，因此需要用特定的标识来标记出来，从而让 AI 忽略它。在 markdown 中，可以用 html-comment 来做这个隐藏的注释（比如`<!-- i18n-ignore-start -->` 与 `<!-- i18n-ignore-end -->`），在 json 中，可以用特殊的字段来做配置（比如`"//key":["i18n-ignore"]`就意味着对`key`对应的 value 做`i18n-ignore`的处理）。
+1. 有些翻译是需要进行本土化翻译，因此也需要用特定的标识标记出来，让 AI 根据本地的情况来进行翻译。在 markdown 中，可以用 html-comment 来做这个隐藏的注释（比如`<!-- i11n-start: some comment message for i11n -->` 与 `<!-- i11n-end -->`），在 json 中，可以用特殊的字段来做配置（比如`"//key":["i11n: some comment message for i11n"]`就意味着对`key`对应的 value 做`i18n-ignore`的处理）。
+   > 关于本土化的翻译，需要依赖 AI 的发散性思维来进行，因此译文和原文差别可能非常大。因此这里的`some comment message for i11n`目的就是为了引导 AI 的翻译方向。如果是使用中文，我会写：`"//key":["i11n: 这是一些内容说明"]`,那么翻译成英文后，这些内容说明同样也要翻译成英文。
+   > 另外，在 AI 本土化翻译完成后，AI 需要额外补充本土化翻译的一些说明：`//key":["i11n: some comment message for i11n","i11n-reason: some reason"]`，这里的`some reason`确实就是写给 AI 自己看的，目的是未来 AI 再对这段进行翻译的时候，配合原文与之前的翻译思路，才能更加正确地对这段本土化翻译的内容做准确的修改。
+   > 另外就需要依赖 loglist，来优化判断关于本土化的翻译到底要不要进行改动。
+
+---
+
+总结来说，这里的工作主要有四个部分：
+
+1. git 工具的封装
+2. 文件读写的封装
+3. 提示词的编写
+4. cli 工具的开发
+
+注意，我使用的语言是 typescript，运行时是 nodejs。