eSearch 国际化翻译工作流完全指南基于 tool.js 的 CSV 翻译管线与源码级原理解析【免费下载链接】eSearch截屏 离线OCR 搜索翻译 以图搜图 贴图 录屏 万向滚动截屏 屏幕翻译 Screenshot Offline OCR Search Translate Search for picture Paste the picture on the screen Screen recorder Omnidirectional scrolling screenshot Screen translator 支持Windows Linux macOS项目地址: https://gitcode.com/GitHub_Trending/es/eSearch本指南以 eSearch 仓库中的lib/translate/readme.md为核心骨架完整讲解该项目多语言i18n的翻译流程如何用tool.js生成 CSV 翻译表、如何借助 git diff 增量跟进翻译进度、如何回写语言包并结合lib/translate/translate.ts与lib/translate/tool.js的源码逐层剖析其背后的数据流与设计原理。读完本文你将掌握一套可复用的“CSV 中转 commit 追踪”翻译工作流并理解 eSearch 从界面文案到多语言渲染的完整链路。一、eSearch 多语言体系概览eSearch 的国际化体系由三部分构成全部位于仓库的lib/translate/目录下source.json源文案表以简体中文为源语言将界面上的每一条中文文案映射为一个 6 位短 ID例如自动搜索: a5dfc5。只有在这里登记过的文案才可能被翻译见 source.json。各语言 JSON翻译表ar.json、en.json、eo.json、es.json、fr.json、ru.json、zh-HANT.json结构为短ID: 翻译文本例如101321: Add to history见 en.json。运行时翻译模块translate.ts渲染进程与主进程通过t()函数在运行时完成文案替换语言不匹配或缺失时给出彩色调试输出见 translate.ts。翻译的数据流是单向的tool.js以source.json为基准生成 CSV 供人工/AI 编辑再把 CSV 回写成对应语言的 JSON程序运行时由translate.ts依据当前语言读取 JSON 完成翻译。目前仓库内登记的语言共有 7 种ar阿拉伯语、en英语、eo世界语、es西班牙语、fr法语、ru俄语、zh-HANT繁体中文加上默认的简体中文zh-HANS。二、翻译工具快速上手生成 CSVtool.js是整套翻译流程的命令行入口见 tool.js核心命令如下node lib/translate/tool.js -l en # 输出 en.csv执行后会在lib/translate/目录下生成en.csv其中每一行对应一条需要翻译的文案格式为abc,你好世界, ...第 1 列文案的短 ID第 2 列简体中文源文案第 3 列目标语言翻译初始为空。参数-a输出全部文字还是增量[!TIP] 选项-a用于输出全部文字。如果你发现原来的翻译存在不足需要修改请使用这一选项。如果你需要跟进翻译即 eSearch 的某些文字已经修改但翻译未修改请不使用这一选项。-aall模式下tool.js会遍历source.json中的每一条文案并全部写入 CSV适合“重译/校对全部文案”的场景node lib/translate/tool.js -l en -a不带-a时tool.js只输出尚未翻译或源文案已变更的条目详见下文第四节“增量翻译机制”适合日常跟进翻译。参数-e附带英文参考英文翻译常能帮助 AI 或译者更准确地理解中文语义此时可加-e输出的 CSV 会多出一列英文参考abc,你好世界,Hello World, ...对应源码中enableEn的判定args.includes(-e)此时每一行扩展为四列ID、中文、英文、目标语言翻译。从源码看-e模式还会在控制台提示 “with en, For more accuracy, please refer to the Chinese(column 2)”见 tool.js即中文列才是翻译的最终依据英文列仅供参考。其他辅助参数从 tool.js 的参数解析可以看到tool.js还内置了若干面向开发者的参数参数说明源码位置-l lang指定生成哪种语言的 CSV如-l en、-l rutool.js-i file.csv导入 CSV 并回写为对应语言的 JSON见第三节tool.js-e输出英文参考列tool.js-p“纯”模式翻译列为空串而非读取已有翻译puretool.js-u为source.json中没有 ID 的中文文案批量生成随机 6 位 IDcrypto.randomUUID前 6 位tool.js--ai lang调用 GPT 接口自动翻译需设置环境变量gpt--ai all表示翻译全部语言tool.js--all file扫描src/下所有.ts源码找出尚未登记到source.json的中文文案tool.js--auto-clean-trans扫描源码从source.json中清理已不再被任何源码引用的废弃文案tool.js三、编辑与保存CSV 回写语言包CSV 生成后即可交给译者或 AI 编辑。readme.md还给出了一条可直接复用的 AI prompt[!TIP] AI prompt“以下是 csv 文件把第二列翻译成 en 并复制到第三列”编辑完成后的 CSV 形如abc,你好世界,Hello World ...保存时执行node lib/translate/tool.js -i en.csv从源码看-i的回写逻辑是见 tool.js由文件名推导语言const lang inputFile.replace(.csv, )即en.csv→ 语言en用csv-parse解析 CSV依赖声明见 package.json以source.json为骨架构造新对象先继承现有翻译再把 CSV 每一行的最后一列i.at(-1)覆盖写入对应 ID以 4 空格缩进的 JSON 格式回写en.json。值得注意即使-e模式下 CSV 有 4 列回写也只会取最后一列即目标语言列因此英文参考列不会污染目标语言包。四、增量翻译机制srcCommit 与 finishId这是 eSearch 翻译工作流最具特色的设计——借助 git 的 diff 能力做增量翻译。工作原理tool.js内定义了一个srcCommit表见 tool.js为每种语言记录两个字段const srcCommit { en: { id: b6b0f2f6, finishId: [] }, // 英语 ru: { id: b6b0f2f6, finishId: [] }, // 俄语 // ... };id该语言翻译所基于的source.json的 commit ID。脚本启动时会通过git log -n 1 --prettyformat:%h -- source.json打印最新的latestSrcId见 tool.jsfinishId已完成的短 ID 列表。生成增量 CSV 时不带-a脚本执行execSync(git diff ${commit.id} master ${sourcePath})即用git diff对比“翻译基准 commit 的 source.json”与当前 master 的 source.json解析出新增/被修改的文案 IDdiffId随后只输出同时满足以下条件的条目source.json中登记过的文案该语言尚未翻译!l[source[i]]或源文案最近发生了变更diffId.includes(...)不在该语言的finishId列表内。工作流建议readme.md给出的完整流程是翻译完某个 ID 后将其添加到对应语言的finishId例如en.finishId.push(a5dfc5)再次输出 CSV 时会忽略这些已完成条目从而专注未翻译/已修改的部分如果某个版本的全部翻译都已完成就把srcCommit[lang].id更新为latestSrcId脚本启动时打印的那个短 hash并清空finishId。这套机制让“跟上 master 的文案变更”变得低成本你不再需要面对全量文案只需要处理 git diff 真正暴露出的增量。五、开发者辅助工具扫描源码中的未登记文案翻译的边界是source.json只有在source.json里定义的文字才能被翻译。如果 UI 上出现无法翻译的硬编码中文通常是开发者新增页面时漏掉了国际化登记。readme.md明确指出若找不到需要翻译的文字可能是某些页面尚未国际化应在 issue 中提交 bug 并指明需要国际化的位置。tool.js为此提供了两个扫描命令# 找出源码中所有未登记到 source.json 的中文文案并显示所在文件名 node lib/translate/tool.js --all # 以 JSON 片段形式输出便于直接粘进 source.json node lib/translate/tool.js --all some/file.ts源码实现上--all会递归遍历src/目录用STRING_REGEX /([])(?:(?!\1).|\\.)*\1/g提取代码字符串字面量再通过启发式过滤含英文小写、纯大写、数字、点号、#开头等均跳过筛选出疑似中文文案最后与source.json的 key 集合做差集输出见 tool.js。指定文件名参数时只扫描该文件并直接输出文案:,格式的 JSON 行方便批量补登记。反向清理则由--auto-clean-trans完成遍历src/全部文件剔除那些在源码中已不再出现、属于历史遗留的source.json条目见 tool.js。另外-u参数可一键为source.json中尚未分配 ID 的文案生成随机短 ID避免手工起名。六、运行时翻译链路translate.ts 与彩色调试输出语言包最终服务于运行时渲染。translate.ts被主进程与多个渲染页面引用例如 src/main/main.ts主进程、src/renderer/setting/setting.ts设置页、src/renderer/editor/editor.ts编辑器、src/renderer/translator/translator.ts翻译页等。语言匹配与切换parseLan(lan)借助xtranslator的matchFitLan将输入语言与getLans()支持的语言做模糊匹配匹配失败回退简体中文zh-HANS见 translate.tsgetLans()动态读取lib/translate/下的所有.json排除source.json与ignore.json作为支持的语言列表见 translate.tslan(lang)完成语言切换zh-HANS直接返回原文本否则加载对应语言 JSON 到内存见 translate.tsgetLanName(lan)返回各语言的本地化名称如ar: عربي、zh-HANT: 繁体中文供设置页语言选择器展示见 translate.ts。缺失文案的彩色提示readme.md的“开发者”一节描述了两种调试输出约定源码中对应st()函数见 translate.ts红色 文案没有在source.json中定义控制台输出文案:,CSS 为color:#f00;background:#fdd蓝色 文案已登记但该语言尚未翻译控制台输出ID: 中文CSS 为color:blue;background:#ddf。借助这两种颜色开发者可以在运行时快速定位“漏登记”与“漏翻译”两类问题。特殊字符与忽略表中文文案常以全角冒号结尾如自动删除换行前的菜单项编辑autoSt()会把结尾的拆出来单独处理再递归拼接回去避免冒号丢失见 translate.tsignore.json维护一个无需翻译的清单当前内容为[×5, ×10]见 ignore.json这类纯数字/符号文案会被st()直接跳过。变量占位符约定source.json中存在带占位符的文案例如已恢复默认设置部分设置需要重启$1生效: f994c3见 source.json。翻译时$1、$2等占位符必须原样保留这是翻译质量审查尤其是 AI 翻译时需要特别注意的约定。七、AI 辅助翻译可选除人工编辑外tool.js还内置了--ai参数可调用 OpenAI 兼容接口完成翻译见 tool.jsexport gptsk-你的密钥 node lib/translate/tool.js --ai en # 翻译英语 node lib/translate/tool.js --ai all # 翻译全部语言源码实现要点必须设置环境变量gptprocess.env.gpt否则直接抛错Please set GPT_TOKEN系统提示词要求“将翻译提供的 JSON不需要任何解释$1,$2等用于变量占位请保留”并通过 few-shot 示例引导模型输出纯 JSON返回结果经过source反查后按 ID 合并回写对应语言 JSON同时在控制台以表格形式打印翻译结果便于核对。该功能为可选链路且依赖外部服务可用性实际贡献翻译时仍以人工 -a全量校对为准。八、总结完整翻译工作流综合以上内容一次规范的翻译贡献可以概括为跟进增量执行node lib/translate/tool.js -l lang不加-a生成只含未翻译/已变更条目的 CSV编辑翻译用 AI prompt 或人工将中文列翻译为目标语言写入第三列可用-e获得英文参考列回写保存node lib/translate/tool.js -i lang.csv将翻译合并进对应语言 JSON登记进度把已完成的短 ID 追加到tool.js中该语言的finishId全部完成后再把srcCommit的id更新为脚本打印的latestSrcId并清空finishId发现漏网用node lib/translate/tool.js --all扫描源码找出未登记的中文文案并补进source.json随后按步骤 2–4 补齐翻译运行时验证运行应用观察控制台红色/蓝色提示分别对应“未登记”与“未翻译”两类问题逐一修复。整套工作流围绕“中文文案即事实来源source of truth、CSV 为翻译中介、git diff 驱动增量”的设计哲学展开配合translate.ts的运行时模糊匹配与彩色调试输出让 eSearch 的多语言维护既轻量又可审计这一模式同样适用于任何以 JSON 为语言包载体的桌面应用国际化场景。【免费下载链接】eSearch截屏 离线OCR 搜索翻译 以图搜图 贴图 录屏 万向滚动截屏 屏幕翻译 Screenshot Offline OCR Search Translate Search for picture Paste the picture on the screen Screen recorder Omnidirectional scrolling screenshot Screen translator 支持Windows Linux macOS项目地址: https://gitcode.com/GitHub_Trending/es/eSearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 eSearch 国际化翻译工作流完全指南：基于 tool.js 的 CSV 翻译管线与源码级原理解析
eSearch 国际化翻译工作流完全指南基于 tool.js 的 CSV 翻译管线与源码级原理解析【免费下载链接】eSearch截屏 离线OCR 搜索翻译 以图搜图 贴图 录屏 万向滚动截屏 屏幕翻译 Screenshot Offline OCR Search Translate Search for picture Paste the picture on the screen Screen recorder Omnidirectional scrolling screenshot Screen translator 支持Windows Linux macOS项目地址: https://gitcode.com/GitHub_Trending/es/eSearch本指南以 eSearch 仓库中的lib/translate/readme.md为核心骨架完整讲解该项目多语言i18n的翻译流程如何用tool.js生成 CSV 翻译表、如何借助 git diff 增量跟进翻译进度、如何回写语言包并结合lib/translate/translate.ts与lib/translate/tool.js的源码逐层剖析其背后的数据流与设计原理。读完本文你将掌握一套可复用的“CSV 中转 commit 追踪”翻译工作流并理解 eSearch 从界面文案到多语言渲染的完整链路。一、eSearch 多语言体系概览eSearch 的国际化体系由三部分构成全部位于仓库的lib/translate/目录下source.json源文案表以简体中文为源语言将界面上的每一条中文文案映射为一个 6 位短 ID例如自动搜索: a5dfc5。只有在这里登记过的文案才可能被翻译见 source.json。各语言 JSON翻译表ar.json、en.json、eo.json、es.json、fr.json、ru.json、zh-HANT.json结构为短ID: 翻译文本例如101321: Add to history见 en.json。运行时翻译模块translate.ts渲染进程与主进程通过t()函数在运行时完成文案替换语言不匹配或缺失时给出彩色调试输出见 translate.ts。翻译的数据流是单向的tool.js以source.json为基准生成 CSV 供人工/AI 编辑再把 CSV 回写成对应语言的 JSON程序运行时由translate.ts依据当前语言读取 JSON 完成翻译。目前仓库内登记的语言共有 7 种ar阿拉伯语、en英语、eo世界语、es西班牙语、fr法语、ru俄语、zh-HANT繁体中文加上默认的简体中文zh-HANS。二、翻译工具快速上手生成 CSVtool.js是整套翻译流程的命令行入口见 tool.js核心命令如下node lib/translate/tool.js -l en # 输出 en.csv执行后会在lib/translate/目录下生成en.csv其中每一行对应一条需要翻译的文案格式为abc,你好世界, ...第 1 列文案的短 ID第 2 列简体中文源文案第 3 列目标语言翻译初始为空。参数-a输出全部文字还是增量[!TIP] 选项-a用于输出全部文字。如果你发现原来的翻译存在不足需要修改请使用这一选项。如果你需要跟进翻译即 eSearch 的某些文字已经修改但翻译未修改请不使用这一选项。-aall模式下tool.js会遍历source.json中的每一条文案并全部写入 CSV适合“重译/校对全部文案”的场景node lib/translate/tool.js -l en -a不带-a时tool.js只输出尚未翻译或源文案已变更的条目详见下文第四节“增量翻译机制”适合日常跟进翻译。参数-e附带英文参考英文翻译常能帮助 AI 或译者更准确地理解中文语义此时可加-e输出的 CSV 会多出一列英文参考abc,你好世界,Hello World, ...对应源码中enableEn的判定args.includes(-e)此时每一行扩展为四列ID、中文、英文、目标语言翻译。从源码看-e模式还会在控制台提示 “with en, For more accuracy, please refer to the Chinese(column 2)”见 tool.js即中文列才是翻译的最终依据英文列仅供参考。其他辅助参数从 tool.js 的参数解析可以看到tool.js还内置了若干面向开发者的参数参数说明源码位置-l lang指定生成哪种语言的 CSV如-l en、-l rutool.js-i file.csv导入 CSV 并回写为对应语言的 JSON见第三节tool.js-e输出英文参考列tool.js-p“纯”模式翻译列为空串而非读取已有翻译puretool.js-u为source.json中没有 ID 的中文文案批量生成随机 6 位 IDcrypto.randomUUID前 6 位tool.js--ai lang调用 GPT 接口自动翻译需设置环境变量gpt--ai all表示翻译全部语言tool.js--all file扫描src/下所有.ts源码找出尚未登记到source.json的中文文案tool.js--auto-clean-trans扫描源码从source.json中清理已不再被任何源码引用的废弃文案tool.js三、编辑与保存CSV 回写语言包CSV 生成后即可交给译者或 AI 编辑。readme.md还给出了一条可直接复用的 AI prompt[!TIP] AI prompt“以下是 csv 文件把第二列翻译成 en 并复制到第三列”编辑完成后的 CSV 形如abc,你好世界,Hello World ...保存时执行node lib/translate/tool.js -i en.csv从源码看-i的回写逻辑是见 tool.js由文件名推导语言const lang inputFile.replace(.csv, )即en.csv→ 语言en用csv-parse解析 CSV依赖声明见 package.json以source.json为骨架构造新对象先继承现有翻译再把 CSV 每一行的最后一列i.at(-1)覆盖写入对应 ID以 4 空格缩进的 JSON 格式回写en.json。值得注意即使-e模式下 CSV 有 4 列回写也只会取最后一列即目标语言列因此英文参考列不会污染目标语言包。四、增量翻译机制srcCommit 与 finishId这是 eSearch 翻译工作流最具特色的设计——借助 git 的 diff 能力做增量翻译。工作原理tool.js内定义了一个srcCommit表见 tool.js为每种语言记录两个字段const srcCommit { en: { id: b6b0f2f6, finishId: [] }, // 英语 ru: { id: b6b0f2f6, finishId: [] }, // 俄语 // ... };id该语言翻译所基于的source.json的 commit ID。脚本启动时会通过git log -n 1 --prettyformat:%h -- source.json打印最新的latestSrcId见 tool.jsfinishId已完成的短 ID 列表。生成增量 CSV 时不带-a脚本执行execSync(git diff ${commit.id} master ${sourcePath})即用git diff对比“翻译基准 commit 的 source.json”与当前 master 的 source.json解析出新增/被修改的文案 IDdiffId随后只输出同时满足以下条件的条目source.json中登记过的文案该语言尚未翻译!l[source[i]]或源文案最近发生了变更diffId.includes(...)不在该语言的finishId列表内。工作流建议readme.md给出的完整流程是翻译完某个 ID 后将其添加到对应语言的finishId例如en.finishId.push(a5dfc5)再次输出 CSV 时会忽略这些已完成条目从而专注未翻译/已修改的部分如果某个版本的全部翻译都已完成就把srcCommit[lang].id更新为latestSrcId脚本启动时打印的那个短 hash并清空finishId。这套机制让“跟上 master 的文案变更”变得低成本你不再需要面对全量文案只需要处理 git diff 真正暴露出的增量。五、开发者辅助工具扫描源码中的未登记文案翻译的边界是source.json只有在source.json里定义的文字才能被翻译。如果 UI 上出现无法翻译的硬编码中文通常是开发者新增页面时漏掉了国际化登记。readme.md明确指出若找不到需要翻译的文字可能是某些页面尚未国际化应在 issue 中提交 bug 并指明需要国际化的位置。tool.js为此提供了两个扫描命令# 找出源码中所有未登记到 source.json 的中文文案并显示所在文件名 node lib/translate/tool.js --all # 以 JSON 片段形式输出便于直接粘进 source.json node lib/translate/tool.js --all some/file.ts源码实现上--all会递归遍历src/目录用STRING_REGEX /([])(?:(?!\1).|\\.)*\1/g提取代码字符串字面量再通过启发式过滤含英文小写、纯大写、数字、点号、#开头等均跳过筛选出疑似中文文案最后与source.json的 key 集合做差集输出见 tool.js。指定文件名参数时只扫描该文件并直接输出文案:,格式的 JSON 行方便批量补登记。反向清理则由--auto-clean-trans完成遍历src/全部文件剔除那些在源码中已不再出现、属于历史遗留的source.json条目见 tool.js。另外-u参数可一键为source.json中尚未分配 ID 的文案生成随机短 ID避免手工起名。六、运行时翻译链路translate.ts 与彩色调试输出语言包最终服务于运行时渲染。translate.ts被主进程与多个渲染页面引用例如 src/main/main.ts主进程、src/renderer/setting/setting.ts设置页、src/renderer/editor/editor.ts编辑器、src/renderer/translator/translator.ts翻译页等。语言匹配与切换parseLan(lan)借助xtranslator的matchFitLan将输入语言与getLans()支持的语言做模糊匹配匹配失败回退简体中文zh-HANS见 translate.tsgetLans()动态读取lib/translate/下的所有.json排除source.json与ignore.json作为支持的语言列表见 translate.tslan(lang)完成语言切换zh-HANS直接返回原文本否则加载对应语言 JSON 到内存见 translate.tsgetLanName(lan)返回各语言的本地化名称如ar: عربي、zh-HANT: 繁体中文供设置页语言选择器展示见 translate.ts。缺失文案的彩色提示readme.md的“开发者”一节描述了两种调试输出约定源码中对应st()函数见 translate.ts红色 文案没有在source.json中定义控制台输出文案:,CSS 为color:#f00;background:#fdd蓝色 文案已登记但该语言尚未翻译控制台输出ID: 中文CSS 为color:blue;background:#ddf。借助这两种颜色开发者可以在运行时快速定位“漏登记”与“漏翻译”两类问题。特殊字符与忽略表中文文案常以全角冒号结尾如自动删除换行前的菜单项编辑autoSt()会把结尾的拆出来单独处理再递归拼接回去避免冒号丢失见 translate.tsignore.json维护一个无需翻译的清单当前内容为[×5, ×10]见 ignore.json这类纯数字/符号文案会被st()直接跳过。变量占位符约定source.json中存在带占位符的文案例如已恢复默认设置部分设置需要重启$1生效: f994c3见 source.json。翻译时$1、$2等占位符必须原样保留这是翻译质量审查尤其是 AI 翻译时需要特别注意的约定。七、AI 辅助翻译可选除人工编辑外tool.js还内置了--ai参数可调用 OpenAI 兼容接口完成翻译见 tool.jsexport gptsk-你的密钥 node lib/translate/tool.js --ai en # 翻译英语 node lib/translate/tool.js --ai all # 翻译全部语言源码实现要点必须设置环境变量gptprocess.env.gpt否则直接抛错Please set GPT_TOKEN系统提示词要求“将翻译提供的 JSON不需要任何解释$1,$2等用于变量占位请保留”并通过 few-shot 示例引导模型输出纯 JSON返回结果经过source反查后按 ID 合并回写对应语言 JSON同时在控制台以表格形式打印翻译结果便于核对。该功能为可选链路且依赖外部服务可用性实际贡献翻译时仍以人工 -a全量校对为准。八、总结完整翻译工作流综合以上内容一次规范的翻译贡献可以概括为跟进增量执行node lib/translate/tool.js -l lang不加-a生成只含未翻译/已变更条目的 CSV编辑翻译用 AI prompt 或人工将中文列翻译为目标语言写入第三列可用-e获得英文参考列回写保存node lib/translate/tool.js -i lang.csv将翻译合并进对应语言 JSON登记进度把已完成的短 ID 追加到tool.js中该语言的finishId全部完成后再把srcCommit的id更新为脚本打印的latestSrcId并清空finishId发现漏网用node lib/translate/tool.js --all扫描源码找出未登记的中文文案并补进source.json随后按步骤 2–4 补齐翻译运行时验证运行应用观察控制台红色/蓝色提示分别对应“未登记”与“未翻译”两类问题逐一修复。整套工作流围绕“中文文案即事实来源source of truth、CSV 为翻译中介、git diff 驱动增量”的设计哲学展开配合translate.ts的运行时模糊匹配与彩色调试输出让 eSearch 的多语言维护既轻量又可审计这一模式同样适用于任何以 JSON 为语言包载体的桌面应用国际化场景。【免费下载链接】eSearch截屏 离线OCR 搜索翻译 以图搜图 贴图 录屏 万向滚动截屏 屏幕翻译 Screenshot Offline OCR Search Translate Search for picture Paste the picture on the screen Screen recorder Omnidirectional scrolling screenshot Screen translator 支持Windows Linux macOS项目地址: https://gitcode.com/GitHub_Trending/es/eSearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考