2026/8/24 8:20:58
FEATURED · 精选文章 
最近在折腾一些本地化项目时遇到了一个老生常谈但又极其恼人的问题面对一堆需要翻译的 JSON 配置文件用传统的机器翻译工具比如某些在线翻译或早期本地化工具处理结果往往惨不忍睹。要么是术语错乱把“button”翻译成“按钮”还算好的有时直接变成“巴顿”要么是句式僵硬完全不符合中文表达习惯更头疼的是JSON 结构稍微复杂点嵌套个数组或对象翻译工具就可能把键名key也给“翻译”了导致程序直接报错配置文件彻底失效。这种“垃圾机翻”不仅没有提升效率反而制造了更多需要人工校对和修复的麻烦。它解决的只是一个“从A语言到B语言字符”的表面转换却完全无视了“配置文件需要被程序正确读取”这个根本前提。直到我开始尝试用新的思路来处理这个问题——利用当前更容易获取的 AI 能力对 JSON 进行“理解式”汉化。整个过程完全免费核心在于方法论的转变从“翻译文本”到“理解并转换结构化数据”。这不仅仅是换一个翻译引擎那么简单。它意味着你需要把 JSON 文件看作一个带有明确语义和结构约束的数据对象而 AI 的任务是在严格保持其机器可读性的前提下对其中的自然语言内容进行高质量本地化。下面我就把这套从踩坑到跑通的完整思路和实操路径拆解给你。1. 为什么传统机翻在 JSON 汉化上会“翻车”在直接动手之前我们必须先搞清楚问题出在哪。盲目替换工具很可能只是从一种坑跳进另一种坑。1.1 JSON 不是纯文本它是结构化的数据这是最核心的认知差异。一个典型的用于界面或配置的 JSON 文件可能长这样{ app: { name: Awesome Tool, version: 1.0.0, settings: { theme: Dark Mode, language: English } }, ui: { buttons: { submit: Submit Form, cancel: Cancel Operation }, messages: { welcome: Welcome, {user}!, error: An unexpected error occurred. Please try again. } } }传统机翻工具会怎么做它们很可能把整个文件或你选中的文本块当作一段连贯的英文段落送进翻译接口。结果可能是键名Key被污染像name、submit这样的键名对程序来说是标识符绝对不能变。但机翻可能把它变成“名称”、“提交”导致程序无法通过data.ui.buttons.submit读取到值。占位符被破坏“Welcome, {user}!”中的{user}是一个变量占位符。机翻可能把它翻译成“欢迎{用户}”虽然看起来只是翻译了单词但如果程序内部是严格匹配字符串“Welcome, {user}!”来替换占位符的那么翻译后的字符串就会匹配失败导致{user}无法被正确替换为实际用户名。格式丢失或混乱引号、括号可能被错误地转换或转义破坏 JSON 格式使其无法被JSON.parse()解析。1.2 语境缺失与术语不一致配置文件中的文本往往非常简短缺乏上下文。例如“Dark Mode”在设置里是“深色模式”但如果出现在一个主题描述文件中可能是“暗黑风格”。“Cancel Operation”在按钮上是“取消操作”但如果是一个日志消息可能是“操作已取消”。传统机翻无法感知这个字符串出现在“buttons”对象下因此可能给出不合适的翻译。更糟糕的是它无法保证同一术语在文件内或跨文件间的一致性今天把“Settings”翻成“设置”明天可能就变成“设定”。1.3 我们的真实需求是什么总结一下我们对 JSON 汉化的需求其实是分层的保真层绝对要求100% 保持 JSON 结构完整键名、格式、占位符、特殊符号原封不动。准确层核心要求对值Value中的自然语言文本进行准确、符合语境的翻译。优雅层进阶要求翻译后的文本符合目标语言习惯术语统一风格一致。传统机翻连第一层“保真”都经常做不到。所以我们的新方法必须围绕“先保真再求好”的原则来设计。2. 新思路将 AI 作为“理解数据结构的翻译官”既然问题出在“不理解结构”那么解决方案就是让翻译过程“理解结构”。我们不需要自己从头写一个解析器而是利用 AI 模型特别是具备强大代码和结构化数据理解能力的模型来担任这个角色。2.1 核心工作流设计整个高质量汉化流程可以抽象为以下四步原始 JSON 文件 - 解析与提取 - AI 理解并翻译 - 重组与验证 - 汉化后 JSON 文件关键在于“解析与提取”和“重组与验证”这两步。AI 只负责中间“理解并翻译”的部分前后端由我们控制的脚本来保证数据无损。2.2 免费 AI 能力的选择“完全免费”是可能的但需要明确边界。这里主要指的是利用免费的 AI API 额度或本地开源模型。大厂免费额度 API例如 OpenAI GPT-3.5 Turbo、Google Gemini Pro、DeepSeek 等通常提供一定量的免费请求额度。对于翻译 JSON 这种单次调用内容不多的任务个人使用完全足够。本地开源模型如果文件敏感或希望完全离线可以使用量化后的轻量级开源模型在本地运行如 Qwen2.5-Coder、CodeLlama 等。虽然翻译质量可能略低于顶级商用模型但针对技术文本和界面用语效果已经远超传统机翻。选择的关键在于该模型必须能可靠地理解并遵循 JSON 格式和指令。代码模型通常在这方面表现更好。3. 实操指南从零开始构建你的 AI JSON 汉化流水线下面我将以一个具体的例子展示如何用 Python 脚本配合 AI API搭建一个最小可行的工作流。我们将汉化一个简单的ui.json文件。3.1 第一步环境与工具准备你需要准备Python 3.8 环境。一个可用的AI API 密钥例如 DeepSeek注册即有免费额度。我们将以 DeepSeek 为例其他 API 类似。安装必要的库requests,json,os。pip install requests3.2 第二步编写核心脚本脚本的核心逻辑是读取 JSON 文件递归遍历所有节点。筛选出需要翻译的文本值通常是字符串类型且排除明显是键名、代码、URL 的内容。将需要翻译的文本连同其路径信息组织成清晰的提示Prompt发送给 AI。严格解析 AI 的返回确保其返回一个结构化的翻译映射表例如原文本到译文的字典。根据这个映射表精准替换原 JSON 中的对应文本值。保存新的 JSON 文件并进行格式验证。以下是简化版的核心代码框架import json import requests import os from typing import Any, Dict, List # 配置你的 AI API API_KEY “你的_DeepSeek_API_Key” API_URL “https://api.deepseek.com/v1/chat/completions” MODEL “deepseek-chat” def translate_text_with_ai(text_list: List[str], context: str) - Dict[str, str]: 调用 AI API 翻译一组文本。 text_list: 需要翻译的原文列表。 context: 上下文描述帮助 AI 理解文本用途如‘这是软件界面的按钮文本’。 返回一个字典{‘原文1’: ‘译文1’, ‘原文2’: ‘译文2’} prompt f 你是一个专业的本地化助手负责将软件界面文本从英文翻译成简体中文。 翻译要求 1. 保持技术术语准确如‘Submit’在按钮上翻译为‘提交’在日志中可能是‘提交了’。 2. 保持简洁符合UI文本特征。 3. **绝对不要**修改任何占位符格式如{{user}}、{{0}}、%s等必须原样保留。 4. **绝对不要**翻译JSON键名key、文件名、URL、代码标识符。 5. 请仅返回一个合法的JSON对象键是原文值是译文。不要任何额外解释。 上下文{context} 需要翻译的文本列表JSON数组 {json.dumps(text_list, ensure_asciiFalse)} 请开始翻译并直接返回JSON对象 headers { “Authorization”: f“Bearer {API_KEY}”, “Content-Type”: “application/json” } data { “model”: MODEL, “messages”: [{“role”: “user”, “content”: prompt}], “temperature”: 0.1, # 低随机性保证一致性 “max_tokens”: 2000 } try: response requests.post(API_URL, headersheaders, jsondata, timeout30) response.raise_for_status() result response.json() ai_response result[“choices”][0][“message”][“content”].strip() # 尝试从响应中提取JSON translation_map json.loads(ai_response) # 简单验证返回的字典键是否与输入的文本列表匹配 if not all(text in translation_map for text in text_list): print(“警告AI返回的翻译映射不完整。”) return translation_map except json.JSONDecodeError as e: print(f“错误无法解析AI返回的JSON。响应内容{ai_response}”) raise e except Exception as e: print(f“调用API失败{e}”) raise e def extract_strings(node: Any, path: str“”, strings_to_translate: List[Dict]None): 递归遍历JSON提取需要翻译的字符串及其路径。 node: 当前JSON节点。 path: 当前节点在JSON中的路径用于精确定位。 strings_to_translate: 存储提取结果的列表每个元素是{‘path’: ‘a.b.c’, ‘text’: ‘原文’}。 if strings_to_translate is None: strings_to_translate [] if isinstance(node, dict): for key, value in node.items(): new_path f“{path}.{key}” if path else key extract_strings(value, new_path, strings_to_translate) elif isinstance(node, list): for i, item in enumerate(node): new_path f“{path}[{i}]” extract_strings(item, new_path, strings_to_translate) elif isinstance(node, str): # 关键筛选逻辑判断这个字符串是否需要翻译 # 示例排除空串、纯数字、看起来像键名无空格短词、URL、文件路径等 if (node and ‘ ‘ in node and # 简单过滤包含空格的更可能是句子 not node.startswith((‘http://‘, ‘https://‘, ‘/’, ‘./’, ‘../’)) and not node.replace(‘ ‘, ‘‘).isalnum() and len(node) 1): # 排除纯字母数字组合 strings_to_translate.append({“path”: path, “text”: node}) # 其他类型数字、布尔、null跳过 return strings_to_translate def replace_strings_in_json(data: Any, translation_map: Dict[str, str], path: str“”): 根据翻译映射表递归地替换JSON中的字符串。 if isinstance(data, dict): new_dict {} for key, value in data.items(): new_path f“{path}.{key}” if path else key new_dict[key] replace_strings_in_json(value, translation_map, new_path) return new_dict elif isinstance(data, list): return [replace_strings_in_json(item, translation_map, f“{path}[{i}]”) for i, item in enumerate(data)] elif isinstance(data, str): # 只有当该字符串在映射表中且当前路径匹配我们提取过的路径逻辑时才替换。 # 这里简化处理直接检查字符串是否在映射表中。更严谨的做法是同时校验路径。 return translation_map.get(data, data) else: return data def localize_json_file(input_file: str, output_file: str, context: str): 主函数本地化一个JSON文件。 # 1. 读取原始JSON with open(input_file, ‘r’, encoding‘utf-8’) as f: original_data json.load(f) # 2. 提取需要翻译的字符串 strings_info extract_strings(original_data) if not strings_info: print(“未发现需要翻译的文本。”) return original_texts [info[“text”] for info in strings_info] print(f“发现 {len(original_texts)} 条待翻译文本。”) # 3. 调用AI进行翻译 print(“正在调用AI翻译…”) try: translation_map translate_text_with_ai(original_texts, context) except Exception as e: print(“翻译过程失败。”, e) return # 4. 替换文本 localized_data replace_strings_in_json(original_data, translation_map) # 5. 写回文件 with open(output_file, ‘w’, encoding‘utf-8’, newline‘\n’) as f: json.dump(localized_data, f, ensure_asciiFalse, indent2) # ensure_asciiFalse 保证输出中文 print(f“汉化完成结果已保存至{output_file}”) # 6. 简单验证尝试重新加载确保JSON格式有效 try: with open(output_file, ‘r’, encoding‘utf-8’) as f: json.load(f) print(“JSON格式验证通过。”) except json.JSONDecodeError as e: print(f“警告输出文件可能包含无效JSON: {e}”) # 使用示例 if __name__ “__main__”: input_json “ui.json” output_json “ui.zh-CN.json” context_description “这是一个软件的用户界面文本JSON文件包含按钮标签、提示消息、设置选项等。” localize_json_file(input_json, output_json, context_description)3.3 第三步关键细节与避坑指南运行上述脚本只是一个开始。要让它在实际项目中稳定工作需要注意以下几点API 调用成本与限流免费额度有速率和总量限制。脚本中一次性发送所有文本如果文本量很大100条可能触发限流或超出上下文长度。改进策略将文本列表分批次例如每批20条发送并在批次间添加短暂休眠time.sleep(1)。翻译质量与上下文context参数至关重要。你需要清晰告诉 AI 文本的用途。例如“这是视频编辑软件的导出设置选项”、“这是错误日志中的描述信息”。这能极大提升术语准确性和语气。键名与特殊值的保护示例中的extract_strings函数筛选逻辑比较简单。在生产环境中你需要更精细的规则例如维护一个“排除词列表”如[“id”, “name”, “type”, “url”, “path”]当字符串作为键名key出现时其值即使可读也不翻译。使用正则表达式更准确地识别和跳过占位符如{{.*?}}、%s、{0}、文件路径、正则表达式模式等。错误处理与重试网络请求可能失败AI 可能返回非 JSON 格式。必须添加重试机制和更健壮的响应解析例如使用正则从返回文本中提取 JSON 块。术语一致性对于大型项目最好先提取一个术语表高频、关键的技术词汇在 Prompt 中提供给 AI要求它优先使用你提供的译法。4. 进阶从单文件脚本到工程化解决方案当你需要处理一个包含成百上千个 JSON 文件的本地化项目时上述脚本就需要进化了。4.1 构建翻译记忆库核心思想是“避免重复翻译并保持一致性”。每次成功翻译后将{原文: 译文}对存储到一个中央数据库如 SQLite或文件中。下次翻译新文件时先查询记忆库。如果找到完全匹配的原文直接使用已有译文。这不仅能节省 API 调用更是保证同一术语在不同文件、不同版本间翻译一致的关键。4.2 实现增量更新与人工校对接口原始文件更新后如何只翻译新增或修改的文本计算每个字符串的哈希值如 MD5并与记忆库中存储的“原文哈希”关联。翻译前先计算当前文件中所有字符串的哈希与记忆库比对。只发送新的或哈希值改变即内容改变的文本去翻译。脚本应能生成一个“待校对文件”如 CSV列出所有 AI 翻译的结果方便人工进行最终审核和微调。审核后的结果可以反馈回记忆库。4.3 集成到开发流程中对于开发团队可以将此汉化流程作为 CI/CD 流水线的一环。开发者提交源代码或资源文件更新。CI 工具如 GitHub Actions自动运行汉化脚本处理指定的 JSON 资源目录。脚本利用记忆库进行增量翻译生成新的本地化文件。自动创建 Pull Request 或提交到对应的本地化分支。本地化负责人只需审核 PR 中的变化而非从头翻译。4.4 探索本地模型方案如果对数据隐私有极高要求或希望实现零成本、离线的汉化可以研究部署本地开源模型。模型选择Qwen2.5-Coder-7B-Instruct、CodeLlama-7B-Instruct 等代码模型在理解指令和结构化数据方面表现良好。通过 Ollama、LM Studio 等工具可以方便地在本地运行。性能权衡本地模型需要 GPU 内存或较长的 CPU 推理时间。翻译质量可能略低于 GPT-4 等顶级模型但对于技术文本通常足够使用。Prompt 设计给本地模型的指令需要更加详细和明确因为它们遵循复杂指令的能力相对较弱。告别“垃圾机翻”的本质不是找到一个更贵的翻译工具而是重新定义问题——将“翻译 JSON 文件”视为一个数据转换任务而非文本翻译任务。AI 在这里扮演的角色是一个能理解数据结构、遵循严格规则、并能进行高质量语言转换的智能处理器。这套方法的价值远不止于省下购买专业本地化软件的费用。它带来的真正改变是可控性和可集成性。你可以精确控制翻译的粒度哪些翻哪些不翻可以轻松融入自己的术语库和风格指南可以将整个流程无缝嵌入到自动化工作流中。从一次性的手动执行到可重复、可积累、可协作的工程化流程这才是应对大量配置文件和界面文本本地化的长久之道。开始行动时建议从一个小而具体的 JSON 文件入手用最简脚本跑通全流程。先验证“保真”能力结构、键名、占位符无损再优化“准确”和“优雅”能力通过改进 Prompt 和上下文。当你手里有一个能稳定处理单个文件的脚本时你就已经拥有了解决更大规模问题的核心武器。剩下的不过是围绕它构建更坚固的工事——记忆库、错误处理、批量调度和流程集成。
告别垃圾机翻：利用AI实现JSON配置文件无损汉化的工程实践
最近在折腾一些本地化项目时遇到了一个老生常谈但又极其恼人的问题面对一堆需要翻译的 JSON 配置文件用传统的机器翻译工具比如某些在线翻译或早期本地化工具处理结果往往惨不忍睹。要么是术语错乱把“button”翻译成“按钮”还算好的有时直接变成“巴顿”要么是句式僵硬完全不符合中文表达习惯更头疼的是JSON 结构稍微复杂点嵌套个数组或对象翻译工具就可能把键名key也给“翻译”了导致程序直接报错配置文件彻底失效。这种“垃圾机翻”不仅没有提升效率反而制造了更多需要人工校对和修复的麻烦。它解决的只是一个“从A语言到B语言字符”的表面转换却完全无视了“配置文件需要被程序正确读取”这个根本前提。直到我开始尝试用新的思路来处理这个问题——利用当前更容易获取的 AI 能力对 JSON 进行“理解式”汉化。整个过程完全免费核心在于方法论的转变从“翻译文本”到“理解并转换结构化数据”。这不仅仅是换一个翻译引擎那么简单。它意味着你需要把 JSON 文件看作一个带有明确语义和结构约束的数据对象而 AI 的任务是在严格保持其机器可读性的前提下对其中的自然语言内容进行高质量本地化。下面我就把这套从踩坑到跑通的完整思路和实操路径拆解给你。1. 为什么传统机翻在 JSON 汉化上会“翻车”在直接动手之前我们必须先搞清楚问题出在哪。盲目替换工具很可能只是从一种坑跳进另一种坑。1.1 JSON 不是纯文本它是结构化的数据这是最核心的认知差异。一个典型的用于界面或配置的 JSON 文件可能长这样{ app: { name: Awesome Tool, version: 1.0.0, settings: { theme: Dark Mode, language: English } }, ui: { buttons: { submit: Submit Form, cancel: Cancel Operation }, messages: { welcome: Welcome, {user}!, error: An unexpected error occurred. Please try again. } } }传统机翻工具会怎么做它们很可能把整个文件或你选中的文本块当作一段连贯的英文段落送进翻译接口。结果可能是键名Key被污染像name、submit这样的键名对程序来说是标识符绝对不能变。但机翻可能把它变成“名称”、“提交”导致程序无法通过data.ui.buttons.submit读取到值。占位符被破坏“Welcome, {user}!”中的{user}是一个变量占位符。机翻可能把它翻译成“欢迎{用户}”虽然看起来只是翻译了单词但如果程序内部是严格匹配字符串“Welcome, {user}!”来替换占位符的那么翻译后的字符串就会匹配失败导致{user}无法被正确替换为实际用户名。格式丢失或混乱引号、括号可能被错误地转换或转义破坏 JSON 格式使其无法被JSON.parse()解析。1.2 语境缺失与术语不一致配置文件中的文本往往非常简短缺乏上下文。例如“Dark Mode”在设置里是“深色模式”但如果出现在一个主题描述文件中可能是“暗黑风格”。“Cancel Operation”在按钮上是“取消操作”但如果是一个日志消息可能是“操作已取消”。传统机翻无法感知这个字符串出现在“buttons”对象下因此可能给出不合适的翻译。更糟糕的是它无法保证同一术语在文件内或跨文件间的一致性今天把“Settings”翻成“设置”明天可能就变成“设定”。1.3 我们的真实需求是什么总结一下我们对 JSON 汉化的需求其实是分层的保真层绝对要求100% 保持 JSON 结构完整键名、格式、占位符、特殊符号原封不动。准确层核心要求对值Value中的自然语言文本进行准确、符合语境的翻译。优雅层进阶要求翻译后的文本符合目标语言习惯术语统一风格一致。传统机翻连第一层“保真”都经常做不到。所以我们的新方法必须围绕“先保真再求好”的原则来设计。2. 新思路将 AI 作为“理解数据结构的翻译官”既然问题出在“不理解结构”那么解决方案就是让翻译过程“理解结构”。我们不需要自己从头写一个解析器而是利用 AI 模型特别是具备强大代码和结构化数据理解能力的模型来担任这个角色。2.1 核心工作流设计整个高质量汉化流程可以抽象为以下四步原始 JSON 文件 - 解析与提取 - AI 理解并翻译 - 重组与验证 - 汉化后 JSON 文件关键在于“解析与提取”和“重组与验证”这两步。AI 只负责中间“理解并翻译”的部分前后端由我们控制的脚本来保证数据无损。2.2 免费 AI 能力的选择“完全免费”是可能的但需要明确边界。这里主要指的是利用免费的 AI API 额度或本地开源模型。大厂免费额度 API例如 OpenAI GPT-3.5 Turbo、Google Gemini Pro、DeepSeek 等通常提供一定量的免费请求额度。对于翻译 JSON 这种单次调用内容不多的任务个人使用完全足够。本地开源模型如果文件敏感或希望完全离线可以使用量化后的轻量级开源模型在本地运行如 Qwen2.5-Coder、CodeLlama 等。虽然翻译质量可能略低于顶级商用模型但针对技术文本和界面用语效果已经远超传统机翻。选择的关键在于该模型必须能可靠地理解并遵循 JSON 格式和指令。代码模型通常在这方面表现更好。3. 实操指南从零开始构建你的 AI JSON 汉化流水线下面我将以一个具体的例子展示如何用 Python 脚本配合 AI API搭建一个最小可行的工作流。我们将汉化一个简单的ui.json文件。3.1 第一步环境与工具准备你需要准备Python 3.8 环境。一个可用的AI API 密钥例如 DeepSeek注册即有免费额度。我们将以 DeepSeek 为例其他 API 类似。安装必要的库requests,json,os。pip install requests3.2 第二步编写核心脚本脚本的核心逻辑是读取 JSON 文件递归遍历所有节点。筛选出需要翻译的文本值通常是字符串类型且排除明显是键名、代码、URL 的内容。将需要翻译的文本连同其路径信息组织成清晰的提示Prompt发送给 AI。严格解析 AI 的返回确保其返回一个结构化的翻译映射表例如原文本到译文的字典。根据这个映射表精准替换原 JSON 中的对应文本值。保存新的 JSON 文件并进行格式验证。以下是简化版的核心代码框架import json import requests import os from typing import Any, Dict, List # 配置你的 AI API API_KEY “你的_DeepSeek_API_Key” API_URL “https://api.deepseek.com/v1/chat/completions” MODEL “deepseek-chat” def translate_text_with_ai(text_list: List[str], context: str) - Dict[str, str]: 调用 AI API 翻译一组文本。 text_list: 需要翻译的原文列表。 context: 上下文描述帮助 AI 理解文本用途如‘这是软件界面的按钮文本’。 返回一个字典{‘原文1’: ‘译文1’, ‘原文2’: ‘译文2’} prompt f 你是一个专业的本地化助手负责将软件界面文本从英文翻译成简体中文。 翻译要求 1. 保持技术术语准确如‘Submit’在按钮上翻译为‘提交’在日志中可能是‘提交了’。 2. 保持简洁符合UI文本特征。 3. **绝对不要**修改任何占位符格式如{{user}}、{{0}}、%s等必须原样保留。 4. **绝对不要**翻译JSON键名key、文件名、URL、代码标识符。 5. 请仅返回一个合法的JSON对象键是原文值是译文。不要任何额外解释。 上下文{context} 需要翻译的文本列表JSON数组 {json.dumps(text_list, ensure_asciiFalse)} 请开始翻译并直接返回JSON对象 headers { “Authorization”: f“Bearer {API_KEY}”, “Content-Type”: “application/json” } data { “model”: MODEL, “messages”: [{“role”: “user”, “content”: prompt}], “temperature”: 0.1, # 低随机性保证一致性 “max_tokens”: 2000 } try: response requests.post(API_URL, headersheaders, jsondata, timeout30) response.raise_for_status() result response.json() ai_response result[“choices”][0][“message”][“content”].strip() # 尝试从响应中提取JSON translation_map json.loads(ai_response) # 简单验证返回的字典键是否与输入的文本列表匹配 if not all(text in translation_map for text in text_list): print(“警告AI返回的翻译映射不完整。”) return translation_map except json.JSONDecodeError as e: print(f“错误无法解析AI返回的JSON。响应内容{ai_response}”) raise e except Exception as e: print(f“调用API失败{e}”) raise e def extract_strings(node: Any, path: str“”, strings_to_translate: List[Dict]None): 递归遍历JSON提取需要翻译的字符串及其路径。 node: 当前JSON节点。 path: 当前节点在JSON中的路径用于精确定位。 strings_to_translate: 存储提取结果的列表每个元素是{‘path’: ‘a.b.c’, ‘text’: ‘原文’}。 if strings_to_translate is None: strings_to_translate [] if isinstance(node, dict): for key, value in node.items(): new_path f“{path}.{key}” if path else key extract_strings(value, new_path, strings_to_translate) elif isinstance(node, list): for i, item in enumerate(node): new_path f“{path}[{i}]” extract_strings(item, new_path, strings_to_translate) elif isinstance(node, str): # 关键筛选逻辑判断这个字符串是否需要翻译 # 示例排除空串、纯数字、看起来像键名无空格短词、URL、文件路径等 if (node and ‘ ‘ in node and # 简单过滤包含空格的更可能是句子 not node.startswith((‘http://‘, ‘https://‘, ‘/’, ‘./’, ‘../’)) and not node.replace(‘ ‘, ‘‘).isalnum() and len(node) 1): # 排除纯字母数字组合 strings_to_translate.append({“path”: path, “text”: node}) # 其他类型数字、布尔、null跳过 return strings_to_translate def replace_strings_in_json(data: Any, translation_map: Dict[str, str], path: str“”): 根据翻译映射表递归地替换JSON中的字符串。 if isinstance(data, dict): new_dict {} for key, value in data.items(): new_path f“{path}.{key}” if path else key new_dict[key] replace_strings_in_json(value, translation_map, new_path) return new_dict elif isinstance(data, list): return [replace_strings_in_json(item, translation_map, f“{path}[{i}]”) for i, item in enumerate(data)] elif isinstance(data, str): # 只有当该字符串在映射表中且当前路径匹配我们提取过的路径逻辑时才替换。 # 这里简化处理直接检查字符串是否在映射表中。更严谨的做法是同时校验路径。 return translation_map.get(data, data) else: return data def localize_json_file(input_file: str, output_file: str, context: str): 主函数本地化一个JSON文件。 # 1. 读取原始JSON with open(input_file, ‘r’, encoding‘utf-8’) as f: original_data json.load(f) # 2. 提取需要翻译的字符串 strings_info extract_strings(original_data) if not strings_info: print(“未发现需要翻译的文本。”) return original_texts [info[“text”] for info in strings_info] print(f“发现 {len(original_texts)} 条待翻译文本。”) # 3. 调用AI进行翻译 print(“正在调用AI翻译…”) try: translation_map translate_text_with_ai(original_texts, context) except Exception as e: print(“翻译过程失败。”, e) return # 4. 替换文本 localized_data replace_strings_in_json(original_data, translation_map) # 5. 写回文件 with open(output_file, ‘w’, encoding‘utf-8’, newline‘\n’) as f: json.dump(localized_data, f, ensure_asciiFalse, indent2) # ensure_asciiFalse 保证输出中文 print(f“汉化完成结果已保存至{output_file}”) # 6. 简单验证尝试重新加载确保JSON格式有效 try: with open(output_file, ‘r’, encoding‘utf-8’) as f: json.load(f) print(“JSON格式验证通过。”) except json.JSONDecodeError as e: print(f“警告输出文件可能包含无效JSON: {e}”) # 使用示例 if __name__ “__main__”: input_json “ui.json” output_json “ui.zh-CN.json” context_description “这是一个软件的用户界面文本JSON文件包含按钮标签、提示消息、设置选项等。” localize_json_file(input_json, output_json, context_description)3.3 第三步关键细节与避坑指南运行上述脚本只是一个开始。要让它在实际项目中稳定工作需要注意以下几点API 调用成本与限流免费额度有速率和总量限制。脚本中一次性发送所有文本如果文本量很大100条可能触发限流或超出上下文长度。改进策略将文本列表分批次例如每批20条发送并在批次间添加短暂休眠time.sleep(1)。翻译质量与上下文context参数至关重要。你需要清晰告诉 AI 文本的用途。例如“这是视频编辑软件的导出设置选项”、“这是错误日志中的描述信息”。这能极大提升术语准确性和语气。键名与特殊值的保护示例中的extract_strings函数筛选逻辑比较简单。在生产环境中你需要更精细的规则例如维护一个“排除词列表”如[“id”, “name”, “type”, “url”, “path”]当字符串作为键名key出现时其值即使可读也不翻译。使用正则表达式更准确地识别和跳过占位符如{{.*?}}、%s、{0}、文件路径、正则表达式模式等。错误处理与重试网络请求可能失败AI 可能返回非 JSON 格式。必须添加重试机制和更健壮的响应解析例如使用正则从返回文本中提取 JSON 块。术语一致性对于大型项目最好先提取一个术语表高频、关键的技术词汇在 Prompt 中提供给 AI要求它优先使用你提供的译法。4. 进阶从单文件脚本到工程化解决方案当你需要处理一个包含成百上千个 JSON 文件的本地化项目时上述脚本就需要进化了。4.1 构建翻译记忆库核心思想是“避免重复翻译并保持一致性”。每次成功翻译后将{原文: 译文}对存储到一个中央数据库如 SQLite或文件中。下次翻译新文件时先查询记忆库。如果找到完全匹配的原文直接使用已有译文。这不仅能节省 API 调用更是保证同一术语在不同文件、不同版本间翻译一致的关键。4.2 实现增量更新与人工校对接口原始文件更新后如何只翻译新增或修改的文本计算每个字符串的哈希值如 MD5并与记忆库中存储的“原文哈希”关联。翻译前先计算当前文件中所有字符串的哈希与记忆库比对。只发送新的或哈希值改变即内容改变的文本去翻译。脚本应能生成一个“待校对文件”如 CSV列出所有 AI 翻译的结果方便人工进行最终审核和微调。审核后的结果可以反馈回记忆库。4.3 集成到开发流程中对于开发团队可以将此汉化流程作为 CI/CD 流水线的一环。开发者提交源代码或资源文件更新。CI 工具如 GitHub Actions自动运行汉化脚本处理指定的 JSON 资源目录。脚本利用记忆库进行增量翻译生成新的本地化文件。自动创建 Pull Request 或提交到对应的本地化分支。本地化负责人只需审核 PR 中的变化而非从头翻译。4.4 探索本地模型方案如果对数据隐私有极高要求或希望实现零成本、离线的汉化可以研究部署本地开源模型。模型选择Qwen2.5-Coder-7B-Instruct、CodeLlama-7B-Instruct 等代码模型在理解指令和结构化数据方面表现良好。通过 Ollama、LM Studio 等工具可以方便地在本地运行。性能权衡本地模型需要 GPU 内存或较长的 CPU 推理时间。翻译质量可能略低于 GPT-4 等顶级模型但对于技术文本通常足够使用。Prompt 设计给本地模型的指令需要更加详细和明确因为它们遵循复杂指令的能力相对较弱。告别“垃圾机翻”的本质不是找到一个更贵的翻译工具而是重新定义问题——将“翻译 JSON 文件”视为一个数据转换任务而非文本翻译任务。AI 在这里扮演的角色是一个能理解数据结构、遵循严格规则、并能进行高质量语言转换的智能处理器。这套方法的价值远不止于省下购买专业本地化软件的费用。它带来的真正改变是可控性和可集成性。你可以精确控制翻译的粒度哪些翻哪些不翻可以轻松融入自己的术语库和风格指南可以将整个流程无缝嵌入到自动化工作流中。从一次性的手动执行到可重复、可积累、可协作的工程化流程这才是应对大量配置文件和界面文本本地化的长久之道。开始行动时建议从一个小而具体的 JSON 文件入手用最简脚本跑通全流程。先验证“保真”能力结构、键名、占位符无损再优化“准确”和“优雅”能力通过改进 Prompt 和上下文。当你手里有一个能稳定处理单个文件的脚本时你就已经拥有了解决更大规模问题的核心武器。剩下的不过是围绕它构建更坚固的工事——记忆库、错误处理、批量调度和流程集成。 
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
