大家好我是专注于分享实用开发技巧的技术博主。在日常开发或使用各类软件、工具时我们经常会遇到需要汉化 JSON 配置文件、语言包或插件的情况。传统的汉化工具如一些自动化脚本或早期工具往往依赖简单的机器翻译导致译文生硬、词不达意甚至出现“垃圾机翻”严重影响使用体验和开发效率。本文将为你彻底解决这个问题。我们将深入探讨如何利用当前先进的 AI 大模型能力实现高质量、高准确度的 JSON 文件汉化。整个过程完全免费无需依赖任何付费 API 或商业软件你可以完全掌控汉化流程与质量。无论你是需要汉化一个前端项目的i18n语言包、一个软件的用户界面配置还是一个游戏模组的描述文件这套方法都能帮你获得媲美人工校对的专业级译文。接下来我将从核心概念讲起逐步拆解实现原理并提供从环境准备、代码编写到批量处理的完整实战方案。同时也会分享提升翻译质量的独家提示词技巧和常见问题排查方法。让我们告别“垃圾机翻”拥抱 AI 赋能的高效汉化。1. 背景与核心概念为什么需要 AI 汉化 JSON在深入技术细节之前我们有必要厘清几个关键概念并理解传统方法的弊端。1.1 什么是 JSON 汉化JSONJavaScript Object Notation是一种轻量级的数据交换格式广泛应用于配置文件、语言包和 API 响应中。所谓“JSON 汉化”特指将 JSON 文件中某些特定字段的值通常是字符串类型从一种语言如英语、日语转换为中文的过程。一个典型的待汉化 JSON 片段可能长这样{ app: { name: Awesome Tool, description: A powerful utility for developers., menu: { file: File, edit: Edit, help: Help } } }汉化的目标是将name、description、file等键对应的英文值转换为符合中文语境和软件术语习惯的译文。1.2 传统机翻工具如 Mtool 类工具的痛点许多开发者曾使用过一些自动化汉化工具或脚本它们通常存在以下问题翻译生硬脱离上下文单纯进行逐词或逐句翻译无法理解字段所在的上下文环境。例如将菜单中的“File”翻译为“文件”是正确的但若是一个游戏技能描述中的“File”意为“列队”翻译成“文件”就闹了笑话。术语不统一同一个英文术语在软件不同位置出现时可能被翻译成不同的中文词导致用户困惑。破坏 JSON 结构一些粗糙的工具可能无法正确处理 JSON 中的转义字符如\n,\、嵌套结构或非字符串值数字、布尔值导致文件格式损坏无法被程序解析。无法处理占位符开发中常用占位符如{0}、%s、{{name}}。低质量机翻可能会翻译这些占位符本身或者打乱它们的顺序导致程序运行时替换出错。1.3 AI 大模型汉化的优势以 OpenAI GPT、DeepSeek、通义千问等为代表的大语言模型为 JSON 汉化带来了革命性的提升理解上下文AI 可以通读整个 JSON 结构理解每个字段所处的“场景”。例如它能区分“key”是“钥匙”还是“按键”。专业术语一致性通过合理的提示词Prompt引导AI 可以记住并统一整个文件中的特定术语翻译。保持格式与占位符AI 能严格遵循指令不修改 JSON 的键key、结构、数字、布尔值以及字符串中的占位符和特殊符号。译文更自然生成的译文更符合中文表达习惯读起来流畅自然。我们的目标就是利用这些 AI 模型的零样本或少样本学习能力构建一个免费、自动化、高质量的汉化流水线。2. 环境准备与核心工具选择实现免费 AI 汉化的核心在于选择一个免费的 AI 模型 API以及编写一个能与之交互并处理 JSON 文件的脚本。这里我们提供两种主流且完全免费的方案。2.1 方案一使用 DeepSeek API推荐DeepSeek 提供了免费且强大的 API非常适合本项目。注册与获取 API Key访问 DeepSeek 开放平台官网并注册账号。在控制台中创建 API Key并妥善保存。免费额度通常足够个人进行大量汉化工作。本地 Python 环境Python 版本建议使用 Python 3.8 及以上版本。必要库我们需要requests库来调用 APIjson库来处理数据tqdm库可选来显示进度。安装命令pip install requests tqdm2.2 方案二使用 Ollama 本地模型完全离线数据安全如果你对数据隐私要求极高或没有网络环境可以在本地部署开源模型。安装 Ollama前往 Ollama 官网下载并安装对应操作系统的版本。拉取模型Ollama 安装后在终端运行命令拉取一个适合的中英翻译模型例如qwen2.5:7b7B参数版本在翻译任务上表现良好对硬件要求相对友好。ollama pull qwen2.5:7bPython 环境同样需要 Python 环境并安装requests库用于调用 Ollama 的本地 API。版本说明本文的代码示例将主要围绕DeepSeek API方案展开因为其准备最简单效果稳定。对于 Ollama 方案我会在相应部分指出调用的区别。所有代码在常见操作系统Windows, macOS, Linux上均可运行。2.3 项目结构规划在开始编码前我们先规划好项目目录使其清晰易懂ai_json_translator/ ├── config.py # 配置文件存放API密钥等 ├── translator.py # 核心翻译器类 ├── main.py # 主程序入口 ├── input.json # 待翻译的原始JSON文件 ├── output.json # 翻译后输出的JSON文件 ├── requirements.txt # 项目依赖列表 └── README.md # 项目说明3. 核心原理与实现拆解我们的汉化程序核心工作流程可以概括为“读取 - 提取 - 翻译 - 回填 - 保存”。下面我们分步拆解其中的关键技术点。3.1 递归遍历提取所有字符串值JSON 结构可能是多层嵌套的。我们需要一个函数能够遍历整个 JSON 对象字典或列表找出所有需要翻译的字符串值str类型同时记住它的“路径”以便翻译后能准确放回原处。关键点跳过 JSON 的键key。通常键是程序识别的标识符不应被翻译。跳过非字符串的值如数字、布尔值true/false、null。需要处理嵌套的字典和列表。3.2 设计高效的 AI 翻译提示词Prompt这是决定翻译质量的核心。一个好的 Prompt 需要明确告诉 AI任务你是一个专业的技术文档/软件界面翻译助手。输入与输出格式输入是一段 JSON 数据输出是翻译成中文的 JSON保持原结构。翻译规则只翻译字符串值不翻译键名。保持术语一致例如全文的“User”都译为“用户”。保留所有数字、布尔值、null和 JSON 格式。严格保留字符串中的代码、变量、占位符如{name}、%s、\n及其顺序。译文需符合中文软件用语习惯简洁准确。示例Few-shot Learning提供一两个简单的例子让 AI 更好地理解格式。3.3 处理长文本与 API 限制AI API 通常有上下文长度Token限制。一个大型的 JSON 文件可能包含成千上万个字符串无法一次性发送。策略我们将需要翻译的字符串列表进行分块Chunking每次发送一个合理大小的块给 AI 进行批量翻译然后汇总结果。3.4 翻译结果回填与校验收到 AI 返回的翻译后我们需要根据之前记录的“路径”将翻译好的字符串逐一写回原始的 JSON 数据结构中。最后将完整的、翻译后的 JSON 对象保存为新的文件。保存前最好进行一次 JSON 格式校验确保生成的文件是有效的。4. 完整实战构建免费 AI JSON 汉化工具现在我们将把上述原理转化为可运行的代码。请跟随步骤一步步操作。4.1 创建项目与安装依赖首先创建项目目录并初始化环境。# 创建项目文件夹 mkdir ai_json_translator cd ai_json_translator # 创建虚拟环境可选但推荐 python -m venv venv # Windows 激活: venv\Scripts\activate # macOS/Linux 激活: source venv/bin/activate # 安装依赖 pip install requests tqdm创建requirements.txt文件requests2.28.0 tqdm4.64.04.2 编写配置文件创建config.py用于管理敏感信息和配置。请务必将此文件加入.gitignore不要提交到公开仓库。# config.py # DeepSeek API 配置 DEEPSEEK_API_KEY your_deepseek_api_key_here # 请替换为你的真实 API Key DEEPSEEK_API_URL https://api.deepseek.com/v1/chat/completions DEEPSEEK_MODEL deepseek-chat # 或其他你拥有的模型 # 翻译配置 TRANSLATION_PROMPT 你是一个专业的软件本地化翻译专家。请将以下 JSON 数据中的字符串值value从英文翻译成简体中文。 请严格遵守以下规则 1. 只翻译字符串类型的值不要翻译键名key。 2. 保持术语一致性。例如如果“User”被翻译为“用户”那么全文都应保持一致。 3. 保留所有 JSON 格式、数字、布尔值(true/false)、null。 4. 严格保留字符串中的所有占位符如 {0}, {name}, %s, %d、换行符(\\n)、HTML标签如 br, colorred及其原始顺序和格式不要翻译或修改它们。 5. 译文应准确、流畅符合中文软件界面和文档的用语习惯。 以下是需要你翻译的 JSON 数据 {text} 请直接返回翻译后的完整 JSON不要添加任何额外的解释。 # Ollama 配置备用 OLLAMA_API_URL http://localhost:11434/api/generate OLLAMA_MODEL qwen2.5:7b # 性能配置 MAX_TOKENS_PER_REQUEST 2000 # 根据模型上下文窗口调整预留空间 TRANSLATION_TIMEOUT 30 # 请求超时时间秒4.3 实现核心翻译器类创建translator.py这是我们工具的心脏。# translator.py import json import time from typing import Any, Dict, List, Tuple import requests from tqdm import tqdm from config import DEEPSEEK_API_KEY, DEEPSEEK_API_URL, DEEPSEEK_MODEL, TRANSLATION_PROMPT, MAX_TOKENS_PER_REQUEST, TRANSLATION_TIMEOUT, OLLAMA_API_URL, OLLAMA_MODEL class JsonTranslator: def __init__(self, use_ollamaFalse): 初始化翻译器 :param use_ollama: 如果为 True则使用本地 Ollama否则使用 DeepSeek API self.use_ollama use_ollama self.session requests.Session() if not use_ollama: self.session.headers.update({ Authorization: fBearer {DEEPSEEK_API_KEY}, Content-Type: application/json }) def _extract_strings_with_path(self, data: Any, path: str ) - List[Tuple[str, str]]: 递归提取 JSON 中所有字符串值及其路径 :param data: 当前处理的 JSON 数据节点 :param path: 当前节点的路径表示用于定位 :return: 列表每个元素是 (路径, 字符串值) strings [] if isinstance(data, dict): for key, value in data.items(): # 构建新路径例如 “app.name” new_path f{path}.{key} if path else key strings.extend(self._extract_strings_with_path(value, new_path)) elif isinstance(data, list): for idx, item in enumerate(data): new_path f{path}[{idx}] strings.extend(self._extract_strings_with_path(item, new_path)) elif isinstance(data, str): # 只收集非空的字符串 if data.strip(): strings.append((path, data)) # 其他类型int, float, bool, None跳过 return strings def _chunk_strings(self, strings: List[Tuple[str, str]]) - List[List[Tuple[str, str]]]: 将待翻译的字符串列表分块以适应 API 的 Token 限制。 这里采用简单的按字符数估算更精确的做法可以调用 tokenizer。 chunks [] current_chunk [] current_chunk_size 0 for path, text in strings: text_size len(text) # 如果当前块已满或加上新文本会超限则开启新块 if current_chunk and (current_chunk_size text_size MAX_TOKENS_PER_REQUEST): chunks.append(current_chunk) current_chunk [] current_chunk_size 0 current_chunk.append((path, text)) current_chunk_size text_size if current_chunk: chunks.append(current_chunk) return chunks def _translate_chunk_deepseek(self, chunk: List[Tuple[str, str]]) - Dict[str, str]: 使用 DeepSeek API 翻译一个字符串块 # 构建一个临时的迷你 JSON 用于发送键为路径值为原文 temp_json {path: text for path, text in chunk} prompt TRANSLATION_PROMPT.format(textjson.dumps(temp_json, ensure_asciiFalse, indent2)) payload { model: DEEPSEEK_MODEL, messages: [ {role: system, content: 你是一个专业的翻译助手。}, {role: user, content: prompt} ], temperature: 0.1, # 低温度保证输出稳定减少随机性 max_tokens: 4000 } try: response self.session.post(DEEPSEEK_API_URL, jsonpayload, timeoutTRANSLATION_TIMEOUT) response.raise_for_status() result response.json() translated_content result[choices][0][message][content].strip() # 尝试解析返回的 JSON # AI 有时会在返回内容外加 json 标记需要处理 if translated_content.startswith(json): translated_content translated_content[7:] # 去掉 json if translated_content.endswith(): translated_content translated_content[:-3] translated_content translated_content.strip() translated_dict json.loads(translated_content) return translated_dict except json.JSONDecodeError as e: print(f解析 AI 返回的 JSON 失败: {e}) print(fAI 返回的内容是:\n{translated_content}) # 应急处理如果解析失败返回一个空字典这个块的翻译将失败 return {} except requests.exceptions.RequestException as e: print(fAPI 请求失败: {e}) return {} def _translate_chunk_ollama(self, chunk: List[Tuple[str, str]]) - Dict[str, str]: 使用本地 Ollama API 翻译一个字符串块 temp_json {path: text for path, text in chunk} prompt TRANSLATION_PROMPT.format(textjson.dumps(temp_json, ensure_asciiFalse, indent2)) payload { model: OLLAMA_MODEL, prompt: prompt, stream: False, options: { temperature: 0.1 } } try: response self.session.post(OLLAMA_API_URL, jsonpayload, timeoutTRANSLATION_TIMEOUT*2) # Ollama可能慢一些 response.raise_for_status() result response.json() translated_content result[response].strip() # 清理可能的标记 if translated_content.startswith(json): translated_content translated_content[7:] if translated_content.endswith(): translated_content translated_content[:-3] translated_content translated_content.strip() translated_dict json.loads(translated_content) return translated_dict except (json.JSONDecodeError, KeyError) as e: print(f解析 Ollama 返回的 JSON 失败: {e}) print(fOllama 返回的内容是:\n{translated_content}) return {} except requests.exceptions.RequestException as e: print(fOllama API 请求失败: {e}) return {} def _update_json_with_translations(self, data: Any, translations: Dict[str, str]): 根据翻译字典将译文写回原始 JSON 数据结构 :param data: 原始的 JSON 数据字典或列表 :param translations: 路径到译文的映射字典 # 这是一个递归辅助函数 def _update(node, path_prefix): if isinstance(node, dict): for key, value in node.items(): current_path f{path_prefix}.{key} if path_prefix else key if isinstance(value, str) and value.strip(): # 如果当前路径的字符串在翻译字典中则替换 if current_path in translations: node[key] translations[current_path] else: # 递归处理子对象 _update(value, current_path) elif isinstance(node, list): for idx, item in enumerate(node): current_path f{path_prefix}[{idx}] if isinstance(item, str) and item.strip(): if current_path in translations: node[idx] translations[current_path] else: _update(item, current_path) _update(data) return data def translate_file(self, input_filepath: str, output_filepath: str): 主翻译函数读取 JSON 文件翻译并保存结果。 print(f开始处理文件: {input_filepath}) # 1. 读取原始 JSON with open(input_filepath, r, encodingutf-8) as f: original_data json.load(f) # 2. 提取所有需要翻译的字符串及其路径 print(正在提取待翻译文本...) strings_to_translate self._extract_strings_with_path(original_data) if not strings_to_translate: print(未找到需要翻译的字符串。) with open(output_filepath, w, encodingutf-8) as f: json.dump(original_data, f, ensure_asciiFalse, indent2) return print(f共找到 {len(strings_to_translate)} 处需要翻译的文本。) # 3. 分块 chunks self._chunk_strings(strings_to_translate) print(f文本已分为 {len(chunks)} 个块进行翻译。) # 4. 逐块翻译 all_translations {} with tqdm(totallen(chunks), desc翻译进度) as pbar: for chunk in chunks: if self.use_ollama: translated_dict self._translate_chunk_ollama(chunk) else: translated_dict self._translate_chunk_deepseek(chunk) # 合并翻译结果 all_translations.update(translated_dict) pbar.update(1) time.sleep(0.5) # 简单限流避免请求过快 print(f成功获取 {len(all_translations)} 条翻译结果。) # 5. 将翻译写回原数据 translated_data self._update_json_with_translations(original_data, all_translations) # 6. 保存翻译后的 JSON with open(output_filepath, w, encodingutf-8) as f: json.dump(translated_data, f, ensure_asciiFalse, indent2) print(f翻译完成结果已保存至: {output_filepath})4.4 编写主程序入口创建main.py作为程序的启动脚本。# main.py import argparse from translator import JsonTranslator def main(): parser argparse.ArgumentParser(description免费 AI JSON 汉化工具) parser.add_argument(input, help输入的 JSON 文件路径) parser.add_argument(-o, --output, help输出的 JSON 文件路径可选默认为 input_translated.json) parser.add_argument(--ollama, actionstore_true, help使用本地 Ollama 代替 DeepSeek API) args parser.parse_args() input_file args.input if args.output: output_file args.output else: # 默认在输入文件名后加 _translated import os base, ext os.path.splitext(input_file) output_file f{base}_translated{ext} # 初始化翻译器 translator JsonTranslator(use_ollamaargs.ollama) # 开始翻译 translator.translate_file(input_file, output_file) if __name__ __main__: main()4.5 准备测试文件并运行在项目根目录下创建一个input.json文件作为测试。{ app: { name: Awesome Tool, description: A powerful utility for developers to manage their projects efficiently., version: 1.0.0, settings: { theme: Dark, language: English, autoSave: true } }, menu: { file: { new: New Project, open: Open..., save: Save, saveAs: Save As..., exit: Exit }, edit: { undo: Undo, redo: Redo, cut: Cut, copy: Copy, paste: Paste }, help: { documentation: Documentation, checkForUpdates: Check for Updates, about: About {appName} } }, messages: { welcome: Hello, {user}! Welcome back., saveSuccess: File {fileName} saved successfully., confirmExit: Are you sure you want to exit? Any unsaved changes will be lost. } }运行程序使用 DeepSeek API确保已在config.py中填写正确的DEEPSEEK_API_KEY。在终端中执行python main.py input.json程序会自动生成input_translated.json文件。运行程序使用 Ollama确保 Ollama 服务已启动通常安装后会自动运行。在终端中执行python main.py input.json --ollama4.6 查看翻译结果打开生成的input_translated.json文件你应该能看到类似以下的高质量译文{ app: { name: Awesome Tool, description: 一款供开发者高效管理项目的强大工具。, version: 1.0.0, settings: { theme: 深色, language: English, autoSave: true } }, menu: { file: { new: 新建项目, open: 打开..., save: 保存, saveAs: 另存为..., exit: 退出 }, edit: { undo: 撤销, redo: 重做, cut: 剪切, copy: 复制, paste: 粘贴 }, help: { documentation: 文档, checkForUpdates: 检查更新, about: 关于 {appName} } }, messages: { welcome: 你好{user}欢迎回来。, saveSuccess: 文件“{fileName}”保存成功。, confirmExit: 确定要退出吗所有未保存的更改将会丢失。 } }请注意键如app,name,version没有被翻译。占位符{appName},{user},{fileName}被完整保留。布尔值true和数字1.0.0保持不变。译文符合软件界面用语习惯如“新建项目”、“另存为”、“撤销”。5. 常见问题与排查思路在实际使用中你可能会遇到一些问题。以下是常见问题的排查指南。问题现象可能原因解决思路ModuleNotFoundError: No module named ‘requests’未安装依赖库。在项目目录下运行pip install -r requirements.txt。401 Client Error: UnauthorizedAPI Key 错误或未设置。1. 检查config.py中的DEEPSEEK_API_KEY是否正确。2. 确认 API Key 是否有余额或权限。json.decoder.JSONDecodeError1. 输入的input.json文件格式错误。2. AI 返回的内容不是合法 JSON。1. 使用在线 JSON 校验工具检查input.json。2. 查看程序打印的 AI 返回内容调整TRANSLATION_PROMPT使其更明确地要求返回纯 JSON。可以在 Prompt 开头强调“请直接返回一个 JSON 对象不要有任何额外文本。”翻译结果缺失或部分未翻译1. 字符串路径在翻译后字典中未匹配。2. 分块导致上下文丢失AI 未能理解某些术语。1. 检查_extract_strings_with_path和_update_json_with_translations中的路径生成和匹配逻辑是否一致。2. 尝试减小MAX_TOKENS_PER_REQUEST让每个块更小或尝试不分组一次性翻译如果文件很小。3. 在 Prompt 中提供更详细的上下文或术语表。翻译质量不佳术语不一致、生硬Prompt 指令不够明确。优化config.py中的TRANSLATION_PROMPT1. 在 Prompt 开头提供术语表。例如“术语表’User’ 请统一翻译为‘用户’’Server’ 翻译为‘服务器’。”2. 要求 AI 进行“本地化”而非直译。使用 Ollama 时连接被拒绝Ollama 服务未运行。1. 在终端运行ollama serve启动服务。2. 检查config.py中的OLLAMA_API_URL是否为http://localhost:11434/api/generate。处理大型 JSON 文件时速度慢或内存不足文件过大一次性加载到内存。1. 对于超大型文件考虑流式读取和分块处理而不是一次性加载整个json.load()。2. 可以按顶级键进行拆分分别翻译后再合并。AI 返回了非 JSON 的说明文字AI 有时会“自作多情”地添加解释。强化 Prompt 的约束力。在TRANSLATION_PROMPT的最后一行用非常强硬的语气写明“你必须只返回一个完整的、格式正确的 JSON 对象不要包含任何其他文字、解释、代码块标记或问候语。”6. 最佳实践与进阶优化指南掌握了基础方法后通过以下实践可以让你汉化的效率和质量更上一层楼。6.1 优化提示词工程Prompt 是灵魂这里提供几个优化方向提供上下文如果可能在发送给 AI 的 JSON 块中包含一些父级键名帮助 AI 理解领域。例如不要只发送{text: Save}而是发送{menu.file.save: Save}。定义术语表在长文档或专业软件汉化前整理一个中英术语对照表放在 Prompt 开头。TERM_GLOSSARY 术语对照表 - “Dashboard” - “仪表板” - “Pipeline” - “流水线” - “Deploy” - “部署” - “Repository” - “仓库” - “Commit” - “提交” TRANSLATION_PROMPT TERM_GLOSSARY TRANSLATION_PROMPT指定风格明确译文风格如“简洁的软件界面用语”、“正式的技术文档风格”、“轻松的游戏对话风格”。6.2 处理特殊格式与标记HTML/XML 标签确保 Prompt 中明确要求保留b,i,color#FF0000等标签。AI 通常能很好地处理。Markdown如果 JSON 值包含 Markdown同样要求 AI 只翻译文本部分保留**粗体**、[链接](url)等语法。多行文本JSON 中的多行字符串含\n会被正确保留。6.3 实现增量翻译与人工校对生成翻译映射文件修改程序在翻译的同时生成一个translation_map.json文件记录每个路径的原文和译文。方便人工校对和复用。{ app.description: { source: A powerful utility for developers..., target: 一款供开发者...的强大工具。 } }加载已有映射在翻译前先加载已有的映射文件跳过已翻译的内容实现增量更新。6.4 集成到自动化流程你可以将此脚本集成到你的构建流程中前端项目在npm run build前自动运行脚本汉化src/locales/en.json输出src/locales/zh-CN.json。游戏开发将工具作为编辑器插件或命令行工具在资源导出后自动汉化配置表。CI/CD 管道在持续集成服务器上设置任务当源语言文件更新时自动触发 AI 汉化并提交到仓库。6.5 性能与成本考量免费额度DeepSeek 等平台的免费额度对于个人和小型项目完全足够。大规模商用前请查阅平台定价策略。缓存机制对翻译结果进行本地缓存如保存到.cache文件相同原文第二次请求时直接使用缓存节省 Token 和费用。超时与重试在网络不稳定或 API 限流时实现简单的重试机制。通过本文的详细讲解你已经掌握了一套完全免费、高质量、可定制化的 AI JSON 汉化解决方案。从理解痛点、环境搭建、原理剖析到代码实战我们一步步构建了一个比传统机翻工具强大得多的自动化工具。关键在于精心设计的 Prompt 和稳健的 JSON 处理逻辑。你可以在此基础上根据具体项目需求进行扩展例如支持更多语言对、集成图形界面、或对接其他 AI 模型。希望这个工具能帮助你彻底告别“垃圾机翻”提升开发和本地化效率。如果在使用中遇到任何问题欢迎在评论区交流探讨。
