🚧 尝试实现增量翻译，目前输出的patch效果不佳

Gaubee · Gaubee · commit ed401ebbbae3 · 2025-01-27T00:56:48.000+08:00
diff --git a/docs/developer/dwebapp/index.md b/docs/developer/dwebapp/index.md
@@ -15,7 +15,7 @@ plaoc 遵循 web 规范，提供一系列的 Api/WebComponent，来满足应用
 基于 DwebBrowser 已经实现了 Android、IOS、MacOS、Windows、Linux 这些主流平台的支持。
 那么也就意味着您的 Web 应用，可以背靠 plaoc 直接实现多端发布。
 
-## 开发 Dweb app 流程
+## 开发 Dwebapp 流程
 
 您首选需要在您的应用根目录下创建 `manifest.json` 文件，您可以认为`manifest.json`等同于 `PWA`的`manifest.json`。
 它主要声明了一些应用的参数和在用户安装的时候做一些展示。
diff --git a/docs/intro.md b/docs/intro.md
@@ -24,7 +24,9 @@ dweb-browser 是一个遵循 Dweb 标准构建起来的浏览器平台，并将
 
 ## 什么是 dweb？
 
-Dweb 是一种去中心化的 Web 共识标准。它直接体现在您的域名上，如： `example.dweb`
+Dweb 是一种去中心化的 Web 共识标准。
+
+它直接体现在您的域名上，如： `example.dweb`
 然而正是因为 dweb 这个跟域名并不在互联网上真实存在，也就意味着它不归属于任何组织，也就是说，如何解释`example.dweb`这个域名，完全由您自己（的设备）执行决策。
 dweb 共识标准由几个部分联合组成：
 
diff --git a/scripts/i18n.ts b/scripts/i18n.ts
@@ -1,16 +1,18 @@
 import OpenAI from "openai";
-import { str_trim_indent } from "@gaubee/util";
+import { func_remember, str_trim_indent } from "@gaubee/util";
 import { z } from "zod";
 import { parseArgs } from "@std/cli/parse-args";
 import { import_meta_ponyfill } from "import-meta-ponyfill";
 import fs from "node:fs";
 import path from "node:path";
 import { config } from "dotenv";
+import { execSync } from "node:child_process";
 
 const zTranslateOptions = z.object({
   file: z.string().array().nonempty(),
   language: z.string().array().nonempty(),
   mode: z.enum(["full", "increment"]),
+  commit: z.string().optional(),
 });
 /**定义一个源文件 */
 const zFile = z.object({
@@ -22,6 +24,11 @@ const zFileWithContent = zFile.merge(
     content: z.string(),
   })
 );
+const zFileWithContentAndDiff = zFileWithContent.merge(
+  z.object({
+    diff: z.string(),
+  })
+);
 /** 差异信息，一种基于git-diff的内容 */
 const zGitDiff = z.string();
 /** 补丁信息，一种基于git-patch的内容 */
@@ -47,13 +54,12 @@ const zModes = {
     input: z.object({
       mode: z.enum(["increment"]),
       /** 输入的文件内容 */
-      files: zFileWithContent.array(),
-      diffs: zGitDiff,
+      changes: zFileWithContentAndDiff.array(),
       /** 输出的文件路径 */
-      outputs: zFile.array(),
+      files: zFileWithContent.array(),
     }),
-    /** 返回参数：翻译好的文件内容 */
-    output: z.object({ patch: zGitPatch }),
+    /** 返回参数：翻译内容的更新补丁 */
+    output: z.object({ files: zFileWithContent.array() }),
   },
 };
 async function translate(args: z.TypeOf<typeof zTranslateOptions>) {
@@ -91,15 +97,68 @@ async function translate(args: z.TypeOf<typeof zTranslateOptions>) {
       files: files,
       outputs: outputs,
     };
+    /// 发送给AI，获得输出
     const output = zModes.full.output.parse(
       await getOpenaiOutput(JSON.stringify(input))
     );
+    /// 处理输出
     output.outputs.forEach((file) => {
       fs.mkdirSync(path.dirname(file.filepath), { recursive: true });
       fs.writeFileSync(file.filepath, file.content);
     });
   } else {
-    // TODO
+    type InputType = z.TypeOf<typeof zModes.increment.input>;
+    const files: InputType["files"] = [];
+    const changes: InputType["changes"] = [];
+    if (args.file.length !== args.language.length) {
+      throw new Error("file and language must be same length");
+    }
+    for (let [index, filepath] of args.file.entries()) {
+      filepath = path.resolve(cwd, filepath);
+      let isFiles = true;
+      let content = "";
+      if (fs.existsSync(filepath)) {
+        content = fs.readFileSync(filepath, "utf-8");
+        if (content.trim() !== "") {
+          const diff = await generateFilePatch({
+            filepath,
+            commit: args.commit,
+          });
+          if (diff !== "") {
+            isFiles = false;
+            changes.push({
+              filepath: filepath,
+              language: args.language[index],
+              diff: diff,
+              content: content,
+            });
+          }
+        }
+      }
+      if (isFiles) {
+        files.push({
+          filepath: filepath,
+          language: args.language[index],
+          content: content,
+        });
+      }
+    }
+    const input: InputType = {
+      mode: args.mode,
+      changes: changes,
+      files: files,
+    };
+    // console.log("input", input);
+
+    /// 发送给AI，获得输出
+    const output = zModes.increment.output.parse(
+      await getOpenaiOutput(JSON.stringify(input))
+    );
+    /// 处理输出
+    output.files.forEach((file) => {
+      fs.mkdirSync(path.dirname(file.filepath), { recursive: true });
+      fs.writeFileSync(file.filepath, file.content);
+    });
   }
 }
 
@@ -113,7 +172,7 @@ const getOpenaiOutput = async (user_content: string) => {
       .parse(process.env.OPENAI_API_KEY),
   });
 
-  const completion = await openai.chat.completions.create({
+  const stream = await openai.chat.completions.create({
     messages: [
       {
         role: "system",
@@ -128,9 +187,7 @@ const getOpenaiOutput = async (user_content: string) => {
       {
         role: "system",
         content: str_trim_indent(`
-          # Translation Protocol v1.2
-      
-          ## 输入输出规范
+          ## 全量翻译的输入输出规范
           输入格式（JSON Schema）：
           \`\`\`json
           {
@@ -152,13 +209,46 @@ const getOpenaiOutput = async (user_content: string) => {
           {
             "outputs": [
               {
-                "filepath": "docs/en/guide.md",
-                "language": "en",
+                "filepath": "<目标路径>",
+                "language": "<目标语言>",
                 "content": "<翻译后的完整内容>"
               }
             ]
           }
           \`\`\`
+
+          ## 增量翻译的输入输出规范
+          输入格式（JSON Schema）：
+          \`\`\`json
+          {
+            "mode": "full",
+            // 这些是有过变更的文件内容
+            "changes": [{
+              "filepath": "<输入路径>",
+              "language": "<输入语言>",
+              "content": "<输入文件内容>",
+              "diff": "<输入文件的变更信息>"
+            }],
+            // 这些是没有变更的文件内容
+            "files": [{
+              "filepath": "<目标路径>",
+              "language": "<目标语言>",
+              "content": "<目标文件内容（可能是空的；也有可能是上一次翻译的内容；也可能是翻译到中途断掉的）>"
+            }]
+          }
+          \`\`\`
+          输出格式（JSON Schema）：
+          \`\`\`json
+          {
+            "files": [
+              {
+                "filepath": "<目标路径> or <目标路径.patch>",
+                "language": "en",
+                "content": "<翻译后的完整内容> or <git apply 格式的内容>"
+              }
+            ]
+          }
+          \`\`\`
       
           ## 翻译规则
           1. 结构保留：
@@ -182,7 +272,23 @@ const getOpenaiOutput = async (user_content: string) => {
           4. 混合内容处理：
           [中文]（原文） → [英文]（翻译） // 保留注释
           "key": "值" // 保留行尾注释
-      
+          
+          5. 对于增量翻译模式，需要理解参数和返回值的含义：
+          - 首先是changes参数，它是指某一个文件的变更记录，使用\`git diff\`获得的差异信息
+          - 然后是files参数，是指其它没有变更的文件。
+          - 最后关于返回值files，会有两种格式：
+          - 第一种是翻译完成的目标文件，包含了全量的内容；
+          - 第二种是 patch 文件后缀，它是可以通过\`git apply\`作用到目标文件的补丁文件，因为如果变更不多，只是几行，那么返回第一种全量内容就没太大意义，所以使用patch格式，可以获得更快的输出结果；
+          -
+          - 关于changes参数的变更内容，主要关注这两种可能：
+          - 第一种是只修改了一种语言，这种情况下，输出的files和输入的files是一一对应的。
+          - 第二种是同时修改了多种语言，这就意味着，变更者是知道多语言的，只不过根据顺序，排在前面的文件，作为源文件的优先级更高。这时候要注意的是，有可能changes[0]改动了第二行，然后changes[1]改动了第10行，那么最终输出的files中，也应该包含这两个changes文件，因为需要将changes[0]改动的第3行翻译给changes[1]，同时也要讲changes[1]改动的第10行翻译给changes[0]。
+          - 
+          - 关于files参数的内容，要关注这有三种可能：
+          - 第一种是，它是一个空文件，那么此时要参考changes[0]的完整内容，做完整的翻译
+          - 第二种是，它是一个翻译到一半就断开的内容，可能是人为的翻译不完整，也有可能是上一次翻译输出不完整，不论如何，仍然是优先参考changes[0]的完整内容，然后参照现有的内容，对剩余没有翻译的部分做补全，通常会返回补丁，但是如果补丁的内容长度已经接近甚至超过翻译后的原文，这时候直接返回原文即可。
+          - 第三种是，它是一个完整的翻译后的内容，这时候主要参考changes[0]的diff内容，来返回补丁内容。
+
           ## 质量要求
           • 术语一致性：保持相同上下文术语统一
           • 格式对齐：译文长度与原文段落结构匹配
@@ -199,14 +305,77 @@ const getOpenaiOutput = async (user_content: string) => {
     response_format: {
       type: "json_object",
     },
+    stream: true,
   });
-  console.log(completion.choices[0].message.content);
-  return JSON.parse(completion.choices[0].message.content!);
+  let res = "";
+  for await (const chunk of stream) {
+    const part = chunk.choices[0].delta.content ?? "";
+    res += part;
+    process.stdout.write(part);
+  }
+  return JSON.parse(res);
 };
 
+interface GeneratePatchOptions {
+  /** 目标文件路径（绝对或相对路径） */
+  filepath: string;
+  /** 目标提交 hash 或引用（默认 HEAD） */
+  commit?: string;
+  /** git 仓库目录 */
+  gitRoot?: string;
+}
+
+const gitRootDir = func_remember(() =>
+  execSync("git rev-parse --show-toplevel", { encoding: "utf-8" }).trim()
+);
+export async function generateFilePatch(
+  options: GeneratePatchOptions
+): Promise<string> {
+  const { filepath, commit = "HEAD" } = options;
+
+  // 获取 Git 仓库根目录
+  const rootDir = options.gitRoot ?? gitRootDir(); // execSync('git rev-parse --show-toplevel', { encoding: 'utf-8' }).trim()
+
+  // 解析绝对路径并验证文件存在
+  const absolutePath = path.resolve(process.cwd(), filepath);
+  if (!fs.existsSync(absolutePath)) {
+    throw new Error(`File not found: ${absolutePath}`);
+  }
+
+  // 转换为仓库相对路径
+  const relativePath = path.relative(rootDir, absolutePath);
+
+  try {
+    // 生成补丁命令
+    const cmd = `git diff ${commit} -- ${JSON.stringify(relativePath)}`;
+
+    // 执行并返回补丁内容
+    return execSync(cmd, {
+      cwd: rootDir,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"], // 忽略 stderr
+    }).trim();
+  } catch (error) {
+    // 处理常见错误
+    if (error instanceof Error) {
+      if (/unknown revision/.test(error.message)) {
+        throw new Error(`Invalid commit hash: ${commit}`);
+      }
+      if (/bad revision/.test(error.message)) {
+        throw new Error(`Cannot find parent commit for: ${commit}`);
+      }
+    }
+    throw new Error(
+      `Failed to generate patch: ${
+        error instanceof Error ? error.message : error
+      }`
+    );
+  }
+}
+
 if (import_meta_ponyfill(import.meta).main) {
   const args = parseArgs(process.argv.slice(2), {
-    string: ["mode"],
+    string: ["mode", "commit"],
     collect: ["file", "language", "env-file"],
     alias: {
       m: "mode",
@@ -216,6 +385,7 @@ if (import_meta_ponyfill(import.meta).main) {
     default: {
       mode: "full",
       "env-file": [".env.local"],
+      commit: "HEAD~1",
     },
   });
 
@@ -225,3 +395,9 @@ if (import_meta_ponyfill(import.meta).main) {
 
   translate(zTranslateOptions.parse(args));
 }
+
+/**
+ * eg:
+ * `node .\scripts\i18n.ts -f .\docs\intro.md -f .\docs\en\intro.md -l zh-Hans -l en`
+ * `node .\scripts\i18n.ts --mode increment -f .\docs\intro.md -f .\docs\en\intro.md -l zh-Hans -l en`
+ */
