游戏本地化最耗时的环节往往不是翻译本身而是“找文本”。一个玩法完整的场景里NPC 对话、任务目标、UI 按钮、物品名称、教学提示全部散落在场景文件里。传统做法是美术或策划在引擎里逐条复制翻译完再逐条粘贴回去漏一条就得返工。这次分享一条更机械化的路径把整个游戏场景当作文本数据源用脚本批量提取字符串调用翻译接口处理再按原格式回写场景文件导回引擎直接跑。这不是某个单一商业插件而是一套通用工作流。核心思路是“场景文件本身就是结构化文本”Godot 的 .tscn、Unity 的 .unity/.prefab 都满足这个条件。只要解析和回写两层做得对翻译层可以接任意翻译服务后续换供应商、加语言、做批量任务都只是脚本参数的变化。整个过程不依赖高端显卡普通开发机 CPU 就能跑重点在于格式解析和批量任务设计。这篇文章会按部署流程展开核心能力速览、适用边界、技术方案拆解、环境准备、提取与回写代码实现、翻译接口接入、批量任务与断点续传、功能验证、性能观察、常见问题排查、最佳实践。代码部分给出可直接运行的通用模板按你的引擎和翻译供应商替换参数就能用。1. 核心能力速览能力项说明目标文件Godot.tscn、Unity.unity/.prefab、其他文本型场景文件核心功能批量提取场景内字符串 - 调用翻译接口 - 按原格式回写硬件门槛普通 CPU 开发机即可不依赖 GPU运行环境Python 3.8仅需标准库和少量第三方库启动方式命令行脚本分“提取”“翻译”“回写”三个阶段运行API 能力支持接入在线翻译服务提供通用 HTTP 调用模板批量任务支持多文件批量处理、翻译缓存、断点续传输出方式默认生成带语言后缀的新场景文件不覆盖原文件适合场景独立游戏出海、小团队多语言版本、demo 本地化验证不适合场景二进制格式场景、需要运行时动态文本的复杂本地化体系如果你在处理 Unreal 的.uasset建议先走 Unreal 自带的 Localization Dashboard而不是直接用脚本改二进制资源。脚本方案的强项是“文本型场景文件”这一点在选型时要先确认。2. 适用场景与使用边界这个方案最典型的用法是“一次性大量文本进机器翻译人工只做最终走查”。比如一个 demo 场景里有 200 条 NPC 对白手动改要半天脚本处理大概几分钟跑完剩下的时间用来核对上下文和术语。适合的情况独立游戏需要快速出多语言版本。外包项目需要把策划写的文本批量转成目标语言。场景文件是小规模文本型格式不需要引入完整本地化框架。需要把相同文本在不同场景里保持一致翻译。不适合的情况游戏有成熟的本地化工具链比如 Unreal 的 Localization Dashboard 或 Unity Localization 包那么应该优先用官方方案。场景内文本包含大量拼接变量、富文本标签、动态 key单纯文本替换会破坏占位符。文本需要根据角色性别、数量、对话分支做条件翻译脚本只适合固定文本不适合复杂规则。涉及未授权内容的翻译和分发。游戏文本、美术对话、版权素材必须在拥有授权的前提下处理。使用边界上要特别注意三点第一调用在线翻译服务时不要把玩家隐私数据、未脱敏的用户内容传入翻译接口第二翻译结果回写后不代表本地化完成字体、行宽、换行和文化禁忌都要人工复核第三涉及商业化发布时确认翻译服务条款允许你保存和使用翻译结果。3. 整体技术方案四个模块把“一键翻译游戏场景”拆开本质是四个模块模块之间通过文本列表和映射字典传递数据互不耦合。3.1 文本提取器文本提取器负责从场景文件里挖出所有可翻译字符串。对这个模块的要求是“宁可多提不要漏提”因为漏掉一句就只能手工补。但也不能把引擎字段名、资源路径、UUID 这类非用户可见文本提取进去否则会把场景结构翻译坏。3.2 翻译适配器翻译适配器负责把文本列表发送给在线翻译服务并返回译文列表。这个模块应该做到“输入输出顺序一致”同时处理超时、限流、失败重试。需要提醒的是翻译接口结果的返回顺序必须和请求内容严格对齐否则回写时会张冠李戴。3.3 回写器回写器把“原文 - 译文”的映射字典应用到场景文件生成新的文件。回写时不能改变原始文件的缩进、引号、换行方式最好只替换字符串字面量其他内容一律不动。3.4 任务调度与缓存批量处理时需要有缓存层。翻译过的字符串单独存一份 JSON 映射下次遇到相同原文直接从缓存读取不用重复调用翻译接口。这样既省钱也保证同一个词在多个场景里的翻译完全一致。4. 环境准备4.1 基础环境Python 3.8 或更高版本。只需要requests库如果场景文件是 JSON 格式则用标准库json如果是 YAML 则需要安装pyyaml。python --version pip install requests pyyaml4.2 样例目录结构game_translate/ ├── scenes/ # 原始场景文件目录 │ ├── level01.tscn │ ├── level02.tscn │ └── ui_main.prefab ├── output/ # 回写后的场景文件目录 ├── scripts/ │ ├── extract.py # 文本提取 │ ├── translate.py # 翻译适配 │ ├── write_back.py # 回写 │ └── batch_run.py # 批量任务入口 ├── translation_cache.json # 翻译缓存 └── translate.log # 日志先建好目录把需要翻译的场景文件复制到scenes/下原始工程文件不要直接作为处理对象避免脚本解析过程中出现问题时污染源文件。4.3 翻译服务准备这个方案不绑定具体翻译供应商。你需要做的是申请一个可用的人工审核键或服务密钥。确认目标语言代码比如中文zh、英文en、日文ja。确认接口支持批量数组传参还是只能一次一个字符串。确认 QPS 限制用于设置并发。翻译服务的选择以合法、合规、已获得服务授权为前提不要使用来源不明的“免费接口”避免文本数据被滥用。5. 功能实现文本提取5.1 Godot 场景文件提取Godot 的.tscn文件本质是文本化场景描述字符串通常以key value形式出现可以直接用正则提取。import re from pathlib import Path def extract_tscn_strings(tscn_path: Path) - list[str]: 提取 Godot .tscn 场景文件中的字符串字面量。 raw tscn_path.read_text(encodingutf-8) # 匹配 text Hello / dialog 你好 这类赋值 pattern re.compile(r\s*([^]*)) result [] for m in pattern.finditer(raw): value m.group(1) if value.strip(): result.append(value) return result if __name__ __main__: demo Path(scenes/level01.tscn) strings extract_tscn_strings(demo) for s in strings: print(s)这个正则方案能覆盖大多数.tscn文件但如果场景里用到了数组、字典中的多行字符串就需要改用 Godot 的资源解析工具或更完整的 YAML 解析。注意.tscn不是标准 YAML只是长得像直接用yaml解析可能报错。5.2 Unity 场景文件提取Unity 的.unity和.prefab是 YAML 格式文本UI 文本组件通常存储为m_Text: Hello脚本组件里也有大量字符串字段。提取思路是逐行扫描m_Text字段。import re from pathlib import Path def extract_unity_texts(unity_file: Path) - list[str]: 提取 Unity 场景文件中的 m_Text 字段。 raw unity_file.read_text(encodingutf-8-sig) pattern re.compile(r^\s*m_Text: (.*)$, re.MULTILINE) result [] for m in pattern.finditer(raw): v m.group(1).strip() if v.startswith() and v.endswith(): value v[1:-1] if value.strip(): result.append(value) elif v ! null: # 有些 m_Text 可能是内联文本按需扩展 continue return result if __name__ __main__: demo Path(scenes/ui_main.prefab) print(extract_unity_texts(demo))注意读取时加了utf-8-sig因为 Unity 场景文件经常带 BOM直接按utf-8读取会在第一个字段前多出不可见字符。写回时也要保留 BOM否则引擎打开可能出现中文乱码。5.3 去重与过滤提取出来的文本列表会有大量重复比如多个 UI 按钮共用“确认”两个字。批量翻译前先排序去重能显著减少 API 调用量。def build_translation_entries(strings: list[str]) - list[str]: return sorted(set(strings))这一步的同时还可以过滤明显不该翻译的内容纯数字、纯文件路径、UUID、只有空格或换行的字符串。具体过滤规则要根据你的项目文本习惯调整。6. 功能实现翻译接接口与回写6.1 翻译接口通用模板这个模板按“批量数组传参”设计如果你的供应商只支持单个字符串就循环调用同时加一个短 sleep 控制频率。import requests # 替换成你自己申请的翻译服务地址和密钥 TRANSLATE_URL https://api.translate-service.example.com/v1/translate TRANSLATE_HEADERS { Content-Type: application/json, Authorization: Bearer YOUR_ACCESS_TOKEN, } def translate_texts(texts: list[str], target_lang: str en) - list[str]: 批量翻译文本返回顺序与输入一致。 if not texts: return [] payload { source: auto, target: target_lang, q: texts, } resp requests.post(TRANSLATE_URL, headersTRANSLATE_HEADERS, jsonpayload, timeout30) resp.raise_for_status() data resp.json() # 各家返回结构不同以下按两种常见结构解析请按实际接口调整 if translations in data: return [item.get(translated_text, ) for item in data[translations]] if result in data: return [item.get(text, item.get(translation, )) for item in data[result]] raise RuntimeError(f无法识别翻译接口返回结构: {data}) if __name__ __main__: texts [Start Game, Options, Quit] translated translate_texts(texts, target_langzh) print(translated)这个模板的解析段很关键。真实项目里翻译服务返回结构五花八门有的把译文直接放到data.translations[0].text有的放到data.data[0].translated。建议第一次接入时先打印完整返回内容手工确认字段名再决定解析逻辑。6.2 Godot 场景回写回写脚本要把映射字典应用到原文生成新文件。这里的关键是保持原文件格式不变只替换双引号中间的内容。import re from pathlib import Path def write_back_tscn(tscn_path: Path, mapping: dict[str, str], suffix: str _zh) - Path: 把翻译映射写回新的 .tscn 文件。 raw tscn_path.read_text(encodingutf-8) out_path tscn_path.with_name(tscn_path.stem suffix tscn_path.suffix) def repl(match): original match.group(1) return f {mapping.get(original, original)} pattern re.compile(r\s*([^]*)) new_raw pattern.sub(repl, raw) out_path.write_text(new_raw, encodingutf-8) return out_path6.3 Unity 场景回写Unity 场景回写同样只是替换m_Text字段。注意两点保留 BOM写回时使用utf-8-sig处理字符串中的转义字符比如\、\\n。import re from pathlib import Path def write_back_unity(unity_path: Path, mapping: dict[str, str], suffix: str _zh) - Path: raw unity_path.read_text(encodingutf-8-sig) out_path unity_path.with_name(unity_path.stem suffix unity_path.suffix) def repl(match): original match.group(1) translated mapping.get(original, original) return fm_Text: {translated} pattern re.compile(r^(\s*)m_Text: (.*)$, re.MULTILINE) new_raw pattern.sub(repl, raw) out_path.write_text(new_raw, encodingutf-8-sig) return out_path这个回写实现是简化版遇到字符串里包含双引号时需要先做反转义否则正则(.*)会从第一个引号匹配到最后一个引号把一段文本截断。稳妥做法是先对原文做转义处理替换结束后再还原。7. 批量任务与断点续传单个场景文件还能用脚本手动处理一旦场景数量到几十个就必须做批量任务。批量任务的三个核心机制是缓存、断点续传和日志。7.1 批量任务入口import json from pathlib import Path from typing import Callable from extract import extract_tscn_strings, extract_unity_texts from translate import translate_texts from write_back import write_back_tscn, write_back_unity def run_batch( scene_files: list[Path], extract_fn: Callable[[Path], list[str]], write_fn: Callable[[Path, dict], Path], target_lang: str zh, cache_file: str translation_cache.json, ) - list[dict]: cache: dict[str, str] {} if Path(cache_file).exists(): cache json.loads(Path(cache_file).read_text(encodingutf-8)) summary [] for scene in scene_files: try: print(f处理: {scene}) # 1. 提取 strings extract_fn(scene) entries sorted(set(strings)) # 2. 翻译优先走缓存 mapping {} pending [] for text in entries: if text in cache: mapping[text] cache[text] else: pending.append(text) if pending: translated translate_texts(pending, target_langtarget_lang) for src, dst in zip(pending, translated): mapping[src] dst cache[src] dst # 3. 回写 out_file write_fn(scene, mapping) summary.append({scene: str(scene), status: OK, output: str(out_file)}) except Exception as e: summary.append({scene: str(scene), status: FAILED, error: str(e)}) # 每个文件处理完立即保存缓存避免中途退出丢失进度 Path(cache_file).write_text( json.dumps(cache, ensure_asciiFalse, indent2), encodingutf-8 ) return summary if __name__ __main__: scenes sorted(Path(scenes).glob(*.tscn)) result run_batch( scenes, extract_fnextract_tscn_strings, write_fnwrite_back_tscn, target_langzh, ) for item in result: print(item)这个入口有几个优点每个文件完成后立即写缓存脚本中断后重新执行已完成的部分不会重复翻译每个文件的错误单独捕获一个文件解析失败不会阻断整个任务返回 summary可以一眼看出哪些文件成功、哪些失败。7.2 并发与限速在线翻译服务基本都有 QPS 限制直接用ThreadPoolExecutor并发调用很容易触发限流。建议先用单线程跑通确认接口稳定后再考虑提升并发。如果接口文档明确支持并发可以控制并发数在 4 到 8 之间并在每次请求之间加 0.1 到 0.2 秒间隔。import time def throttle_delay(seconds: float 0.2): time.sleep(seconds)7.3 日志与失败重试批量任务至少要在日志里记录三块信息哪个文件处理成功、哪个文件失败、失败原因。翻译接口偶发超时是常态简单重试机制很有必要。import time def translate_with_retry(texts: list[str], target_lang: str zh, max_retries: int 3): for attempt in range(max_retries): try: return translate_texts(texts, target_langtarget_lang) except Exception as e: if attempt max_retries - 1: wait 2 ** attempt print(f翻译失败{wait}s 后重试{e}) time.sleep(wait) else: raise8. 功能测试与效果验证脚本写完不要直接拿全部场景跑先用一个最小场景做全流程验证。8.1 测试流程在scenes/下放一个只包含两三句文本的测试场景。运行批量任务生成带_zh后缀的新文件。打开新文件确认字符串已被替换。把新文件导入引擎确认场景能正常加载。跑一遍游戏流程重点看 UI 是否溢出、对话是否有断行。8.2 判断成功标准新场景文件和原文件结构一致缩进、属性顺序没有变化。所有目标文本都被翻译没有残留原文。非文本字段路径、ID、Prefab 引用没有被改动。引擎能直接加载新场景没有报错。目标语言下文字显示完整没有乱码。8.3 常见失败原因正则只匹配了双引号但场景里使用了单引号字符串。文本字段包含转义引号导致正则匹配范围错误。翻译接口返回顺序和请求顺序不一致。场景文件编码不是 UTF-8读取时发生 UnicodeDecodeError。回写后 Unity 文件丢失 BOM或者 Godot 文件被自动格式化成 CRLF。每一类失败都要先在小样本上复现再改提取或回写逻辑不要直接全量重跑。9. 资源占用与性能观察这套方案是纯 CPU 批量任务不涉及 GPU 推理性能瓶颈主要在三个位置。9.1 场景文件解析Godot 和 Unity 场景文件通常是几 MB 到几十 MB正则解析在普通笔记本上运行很快单个文件解析时间以秒为单位。真正慢的是超大型场景几十 MB 的 YAML 文件反复做正则替换内存占用会上升。处理这类文件时建议把文本读取、替换、写出分开不要一次性把所有场景文件全读进内存。9.2 翻译 API 调用大部分耗时在网络请求。100 条文本用批量接口一次调用可能只要几秒如果用单条接口逐条调用按 0.2 秒一条计算100 条就是 20 秒。所以优先用支持数组参数的批量接口这是最有效的性能优化手段。9.3 缓存命中率第一次跑完全量翻译后后续新增语言或增量场景时缓存命中率越高处理时间越短。如果两次只改了一句话新语言的全量翻译依然要重新调用接口这一点在预算评估时要考虑进去。9.4 观察方法运行批量任务时用任务管理器或top观察 CPU 和内存。CPU 会短暂拉高内存取决于场景文件大小如果内存占用持续增长说明代码里有累积引用需要检查是不是把读取出来的大字符串一直保留在变量里。10. 常见问题与排查方法问题现象可能原因排查方式解决方案UnicodeDecodeError场景文件编码不是 UTF-8用文本编辑器查看文件编码读取时指定编码Unity 文件用utf-8-sig翻译后场景打不开回写时破坏了 YAML 结构用 diff 工具对比原文件和回写文件回写前先做格式校验确保只替换字符串字面量部分文本没有翻译正则没有匹配到单引号或多行字符串打印提取结果检查遗漏文本格式扩展正则或改用引擎提供的资源解析工具翻译结果顺序错乱接口返回顺序与请求顺序不一致打印返回的原始 JSON按接口文档调整解析逻辑增加原文与译文配对校验接口返回 429请求频率超过 QPS 限制检查日志中的 HTTP 状态码增加 sleep 间隔降低并发数长文本被截断接口对单条文本长度有限制查看请求返回的截断内容按长文本阈值拆分成多条后分别翻译回写后 Unity 中文乱码文件 BOM 丢失或编码不是 UTF-8用十六进制查看文件头统一使用utf-8-sig写回缓存在脚本中断后失效缓存只在全部完成后写入检查是否每个文件后立即写缓存改为每处理一个文件保存一次缓存翻译后 UI 文字溢出英文转中文后文本长度增加在引擎里直接观察运行效果预留文本空间或启用字体自适应、文本裁剪、多语言字表11. 最佳实践与使用建议11.1 工程化地管理场景文件场景文件是美术和策划每天都在改的文件直接在原文件上做翻译替换非常危险。建议场景文件先复制到一个独立目录脚本只处理副本人工确认后再把翻译结果合并回正式工程。整个过程用版本管理工具记录变更出现问题时可以随时回滚。11.2 构建“原文-译文”双层校验翻译接口并不可靠到可以直接信任。在大规模批处理后应该写一个独立的校验脚本对比每个场景文件中还有没有残留的源语言关键词。如果原文包含特定敏感标识或功能 flag这部分文本必须强制跳过不能进翻译流程。11.3 在缓存中维护术语一致性同一个词在不同场景里出现例如“攻击”“确认”“背包”如果一次一次调用翻译接口结果可能不一致。解决方案很简单缓存先查原文命中的直接复用已有译文。只要第一次翻译时人工校正术语后续所有场景都会自动沿用同一套译法。11.4 可视化回写前先做引擎内验证不要等几十个场景全部回写完再打开引擎看结果。先挑一个典型场景导回引擎跑一段完整流程确认没有加载错误、没有文字乱码、没有功能按键文案错位。通过后再执行全量回写。11.5 合规与授权提醒使用在线翻译服务传输游戏文本要确认文本内容不包含用户隐私、未公开的商业策划内容、未授权第三方版权素材。如果你的游戏还在保密开发期建议使用私有化部署的翻译模型或签署过保密协议的商用翻译服务。发布多语言版本前核对目标地区的文化禁忌和字体授权确保目标语言字库有合法商用授权。12. 总结与下一步这套工作流最值得尝试的点是把“翻译游戏场景”从手工操作变成了可重复执行的脚本流程。提取、翻译、回写三个环节彻底分开以后你可以替换任何一层换翻译供应商、加新语言、调整提取规则都不影响其他模块。最先应该验证的是你自己的场景文件格式确认m_Text和text ...的提取正则能覆盖项目里的真实文本。最容易踩的坑是回写时破坏场景结构所以务必先在副本上跑再进引擎验证。后续可以继续扩展的方向包括接入本地运行的翻译模型、增加术语表强制替换、把批量任务做成 Web 管理界面、接入游戏本地化平台。对独立游戏来说这套方案已经能把多语言版本的生产时间从几天压缩到半天以内。如果现在手头就有带大量文本的场景文件建议先复制一个副本按文章里的模板跑一遍提取看看能提出来多少条字符串这比继续纠结工具选型更有价值。
游戏本地化自动化：场景文件文本提取、翻译与回写全流程
游戏本地化最耗时的环节往往不是翻译本身而是“找文本”。一个玩法完整的场景里NPC 对话、任务目标、UI 按钮、物品名称、教学提示全部散落在场景文件里。传统做法是美术或策划在引擎里逐条复制翻译完再逐条粘贴回去漏一条就得返工。这次分享一条更机械化的路径把整个游戏场景当作文本数据源用脚本批量提取字符串调用翻译接口处理再按原格式回写场景文件导回引擎直接跑。这不是某个单一商业插件而是一套通用工作流。核心思路是“场景文件本身就是结构化文本”Godot 的 .tscn、Unity 的 .unity/.prefab 都满足这个条件。只要解析和回写两层做得对翻译层可以接任意翻译服务后续换供应商、加语言、做批量任务都只是脚本参数的变化。整个过程不依赖高端显卡普通开发机 CPU 就能跑重点在于格式解析和批量任务设计。这篇文章会按部署流程展开核心能力速览、适用边界、技术方案拆解、环境准备、提取与回写代码实现、翻译接口接入、批量任务与断点续传、功能验证、性能观察、常见问题排查、最佳实践。代码部分给出可直接运行的通用模板按你的引擎和翻译供应商替换参数就能用。1. 核心能力速览能力项说明目标文件Godot.tscn、Unity.unity/.prefab、其他文本型场景文件核心功能批量提取场景内字符串 - 调用翻译接口 - 按原格式回写硬件门槛普通 CPU 开发机即可不依赖 GPU运行环境Python 3.8仅需标准库和少量第三方库启动方式命令行脚本分“提取”“翻译”“回写”三个阶段运行API 能力支持接入在线翻译服务提供通用 HTTP 调用模板批量任务支持多文件批量处理、翻译缓存、断点续传输出方式默认生成带语言后缀的新场景文件不覆盖原文件适合场景独立游戏出海、小团队多语言版本、demo 本地化验证不适合场景二进制格式场景、需要运行时动态文本的复杂本地化体系如果你在处理 Unreal 的.uasset建议先走 Unreal 自带的 Localization Dashboard而不是直接用脚本改二进制资源。脚本方案的强项是“文本型场景文件”这一点在选型时要先确认。2. 适用场景与使用边界这个方案最典型的用法是“一次性大量文本进机器翻译人工只做最终走查”。比如一个 demo 场景里有 200 条 NPC 对白手动改要半天脚本处理大概几分钟跑完剩下的时间用来核对上下文和术语。适合的情况独立游戏需要快速出多语言版本。外包项目需要把策划写的文本批量转成目标语言。场景文件是小规模文本型格式不需要引入完整本地化框架。需要把相同文本在不同场景里保持一致翻译。不适合的情况游戏有成熟的本地化工具链比如 Unreal 的 Localization Dashboard 或 Unity Localization 包那么应该优先用官方方案。场景内文本包含大量拼接变量、富文本标签、动态 key单纯文本替换会破坏占位符。文本需要根据角色性别、数量、对话分支做条件翻译脚本只适合固定文本不适合复杂规则。涉及未授权内容的翻译和分发。游戏文本、美术对话、版权素材必须在拥有授权的前提下处理。使用边界上要特别注意三点第一调用在线翻译服务时不要把玩家隐私数据、未脱敏的用户内容传入翻译接口第二翻译结果回写后不代表本地化完成字体、行宽、换行和文化禁忌都要人工复核第三涉及商业化发布时确认翻译服务条款允许你保存和使用翻译结果。3. 整体技术方案四个模块把“一键翻译游戏场景”拆开本质是四个模块模块之间通过文本列表和映射字典传递数据互不耦合。3.1 文本提取器文本提取器负责从场景文件里挖出所有可翻译字符串。对这个模块的要求是“宁可多提不要漏提”因为漏掉一句就只能手工补。但也不能把引擎字段名、资源路径、UUID 这类非用户可见文本提取进去否则会把场景结构翻译坏。3.2 翻译适配器翻译适配器负责把文本列表发送给在线翻译服务并返回译文列表。这个模块应该做到“输入输出顺序一致”同时处理超时、限流、失败重试。需要提醒的是翻译接口结果的返回顺序必须和请求内容严格对齐否则回写时会张冠李戴。3.3 回写器回写器把“原文 - 译文”的映射字典应用到场景文件生成新的文件。回写时不能改变原始文件的缩进、引号、换行方式最好只替换字符串字面量其他内容一律不动。3.4 任务调度与缓存批量处理时需要有缓存层。翻译过的字符串单独存一份 JSON 映射下次遇到相同原文直接从缓存读取不用重复调用翻译接口。这样既省钱也保证同一个词在多个场景里的翻译完全一致。4. 环境准备4.1 基础环境Python 3.8 或更高版本。只需要requests库如果场景文件是 JSON 格式则用标准库json如果是 YAML 则需要安装pyyaml。python --version pip install requests pyyaml4.2 样例目录结构game_translate/ ├── scenes/ # 原始场景文件目录 │ ├── level01.tscn │ ├── level02.tscn │ └── ui_main.prefab ├── output/ # 回写后的场景文件目录 ├── scripts/ │ ├── extract.py # 文本提取 │ ├── translate.py # 翻译适配 │ ├── write_back.py # 回写 │ └── batch_run.py # 批量任务入口 ├── translation_cache.json # 翻译缓存 └── translate.log # 日志先建好目录把需要翻译的场景文件复制到scenes/下原始工程文件不要直接作为处理对象避免脚本解析过程中出现问题时污染源文件。4.3 翻译服务准备这个方案不绑定具体翻译供应商。你需要做的是申请一个可用的人工审核键或服务密钥。确认目标语言代码比如中文zh、英文en、日文ja。确认接口支持批量数组传参还是只能一次一个字符串。确认 QPS 限制用于设置并发。翻译服务的选择以合法、合规、已获得服务授权为前提不要使用来源不明的“免费接口”避免文本数据被滥用。5. 功能实现文本提取5.1 Godot 场景文件提取Godot 的.tscn文件本质是文本化场景描述字符串通常以key value形式出现可以直接用正则提取。import re from pathlib import Path def extract_tscn_strings(tscn_path: Path) - list[str]: 提取 Godot .tscn 场景文件中的字符串字面量。 raw tscn_path.read_text(encodingutf-8) # 匹配 text Hello / dialog 你好 这类赋值 pattern re.compile(r\s*([^]*)) result [] for m in pattern.finditer(raw): value m.group(1) if value.strip(): result.append(value) return result if __name__ __main__: demo Path(scenes/level01.tscn) strings extract_tscn_strings(demo) for s in strings: print(s)这个正则方案能覆盖大多数.tscn文件但如果场景里用到了数组、字典中的多行字符串就需要改用 Godot 的资源解析工具或更完整的 YAML 解析。注意.tscn不是标准 YAML只是长得像直接用yaml解析可能报错。5.2 Unity 场景文件提取Unity 的.unity和.prefab是 YAML 格式文本UI 文本组件通常存储为m_Text: Hello脚本组件里也有大量字符串字段。提取思路是逐行扫描m_Text字段。import re from pathlib import Path def extract_unity_texts(unity_file: Path) - list[str]: 提取 Unity 场景文件中的 m_Text 字段。 raw unity_file.read_text(encodingutf-8-sig) pattern re.compile(r^\s*m_Text: (.*)$, re.MULTILINE) result [] for m in pattern.finditer(raw): v m.group(1).strip() if v.startswith() and v.endswith(): value v[1:-1] if value.strip(): result.append(value) elif v ! null: # 有些 m_Text 可能是内联文本按需扩展 continue return result if __name__ __main__: demo Path(scenes/ui_main.prefab) print(extract_unity_texts(demo))注意读取时加了utf-8-sig因为 Unity 场景文件经常带 BOM直接按utf-8读取会在第一个字段前多出不可见字符。写回时也要保留 BOM否则引擎打开可能出现中文乱码。5.3 去重与过滤提取出来的文本列表会有大量重复比如多个 UI 按钮共用“确认”两个字。批量翻译前先排序去重能显著减少 API 调用量。def build_translation_entries(strings: list[str]) - list[str]: return sorted(set(strings))这一步的同时还可以过滤明显不该翻译的内容纯数字、纯文件路径、UUID、只有空格或换行的字符串。具体过滤规则要根据你的项目文本习惯调整。6. 功能实现翻译接接口与回写6.1 翻译接口通用模板这个模板按“批量数组传参”设计如果你的供应商只支持单个字符串就循环调用同时加一个短 sleep 控制频率。import requests # 替换成你自己申请的翻译服务地址和密钥 TRANSLATE_URL https://api.translate-service.example.com/v1/translate TRANSLATE_HEADERS { Content-Type: application/json, Authorization: Bearer YOUR_ACCESS_TOKEN, } def translate_texts(texts: list[str], target_lang: str en) - list[str]: 批量翻译文本返回顺序与输入一致。 if not texts: return [] payload { source: auto, target: target_lang, q: texts, } resp requests.post(TRANSLATE_URL, headersTRANSLATE_HEADERS, jsonpayload, timeout30) resp.raise_for_status() data resp.json() # 各家返回结构不同以下按两种常见结构解析请按实际接口调整 if translations in data: return [item.get(translated_text, ) for item in data[translations]] if result in data: return [item.get(text, item.get(translation, )) for item in data[result]] raise RuntimeError(f无法识别翻译接口返回结构: {data}) if __name__ __main__: texts [Start Game, Options, Quit] translated translate_texts(texts, target_langzh) print(translated)这个模板的解析段很关键。真实项目里翻译服务返回结构五花八门有的把译文直接放到data.translations[0].text有的放到data.data[0].translated。建议第一次接入时先打印完整返回内容手工确认字段名再决定解析逻辑。6.2 Godot 场景回写回写脚本要把映射字典应用到原文生成新文件。这里的关键是保持原文件格式不变只替换双引号中间的内容。import re from pathlib import Path def write_back_tscn(tscn_path: Path, mapping: dict[str, str], suffix: str _zh) - Path: 把翻译映射写回新的 .tscn 文件。 raw tscn_path.read_text(encodingutf-8) out_path tscn_path.with_name(tscn_path.stem suffix tscn_path.suffix) def repl(match): original match.group(1) return f {mapping.get(original, original)} pattern re.compile(r\s*([^]*)) new_raw pattern.sub(repl, raw) out_path.write_text(new_raw, encodingutf-8) return out_path6.3 Unity 场景回写Unity 场景回写同样只是替换m_Text字段。注意两点保留 BOM写回时使用utf-8-sig处理字符串中的转义字符比如\、\\n。import re from pathlib import Path def write_back_unity(unity_path: Path, mapping: dict[str, str], suffix: str _zh) - Path: raw unity_path.read_text(encodingutf-8-sig) out_path unity_path.with_name(unity_path.stem suffix unity_path.suffix) def repl(match): original match.group(1) translated mapping.get(original, original) return fm_Text: {translated} pattern re.compile(r^(\s*)m_Text: (.*)$, re.MULTILINE) new_raw pattern.sub(repl, raw) out_path.write_text(new_raw, encodingutf-8-sig) return out_path这个回写实现是简化版遇到字符串里包含双引号时需要先做反转义否则正则(.*)会从第一个引号匹配到最后一个引号把一段文本截断。稳妥做法是先对原文做转义处理替换结束后再还原。7. 批量任务与断点续传单个场景文件还能用脚本手动处理一旦场景数量到几十个就必须做批量任务。批量任务的三个核心机制是缓存、断点续传和日志。7.1 批量任务入口import json from pathlib import Path from typing import Callable from extract import extract_tscn_strings, extract_unity_texts from translate import translate_texts from write_back import write_back_tscn, write_back_unity def run_batch( scene_files: list[Path], extract_fn: Callable[[Path], list[str]], write_fn: Callable[[Path, dict], Path], target_lang: str zh, cache_file: str translation_cache.json, ) - list[dict]: cache: dict[str, str] {} if Path(cache_file).exists(): cache json.loads(Path(cache_file).read_text(encodingutf-8)) summary [] for scene in scene_files: try: print(f处理: {scene}) # 1. 提取 strings extract_fn(scene) entries sorted(set(strings)) # 2. 翻译优先走缓存 mapping {} pending [] for text in entries: if text in cache: mapping[text] cache[text] else: pending.append(text) if pending: translated translate_texts(pending, target_langtarget_lang) for src, dst in zip(pending, translated): mapping[src] dst cache[src] dst # 3. 回写 out_file write_fn(scene, mapping) summary.append({scene: str(scene), status: OK, output: str(out_file)}) except Exception as e: summary.append({scene: str(scene), status: FAILED, error: str(e)}) # 每个文件处理完立即保存缓存避免中途退出丢失进度 Path(cache_file).write_text( json.dumps(cache, ensure_asciiFalse, indent2), encodingutf-8 ) return summary if __name__ __main__: scenes sorted(Path(scenes).glob(*.tscn)) result run_batch( scenes, extract_fnextract_tscn_strings, write_fnwrite_back_tscn, target_langzh, ) for item in result: print(item)这个入口有几个优点每个文件完成后立即写缓存脚本中断后重新执行已完成的部分不会重复翻译每个文件的错误单独捕获一个文件解析失败不会阻断整个任务返回 summary可以一眼看出哪些文件成功、哪些失败。7.2 并发与限速在线翻译服务基本都有 QPS 限制直接用ThreadPoolExecutor并发调用很容易触发限流。建议先用单线程跑通确认接口稳定后再考虑提升并发。如果接口文档明确支持并发可以控制并发数在 4 到 8 之间并在每次请求之间加 0.1 到 0.2 秒间隔。import time def throttle_delay(seconds: float 0.2): time.sleep(seconds)7.3 日志与失败重试批量任务至少要在日志里记录三块信息哪个文件处理成功、哪个文件失败、失败原因。翻译接口偶发超时是常态简单重试机制很有必要。import time def translate_with_retry(texts: list[str], target_lang: str zh, max_retries: int 3): for attempt in range(max_retries): try: return translate_texts(texts, target_langtarget_lang) except Exception as e: if attempt max_retries - 1: wait 2 ** attempt print(f翻译失败{wait}s 后重试{e}) time.sleep(wait) else: raise8. 功能测试与效果验证脚本写完不要直接拿全部场景跑先用一个最小场景做全流程验证。8.1 测试流程在scenes/下放一个只包含两三句文本的测试场景。运行批量任务生成带_zh后缀的新文件。打开新文件确认字符串已被替换。把新文件导入引擎确认场景能正常加载。跑一遍游戏流程重点看 UI 是否溢出、对话是否有断行。8.2 判断成功标准新场景文件和原文件结构一致缩进、属性顺序没有变化。所有目标文本都被翻译没有残留原文。非文本字段路径、ID、Prefab 引用没有被改动。引擎能直接加载新场景没有报错。目标语言下文字显示完整没有乱码。8.3 常见失败原因正则只匹配了双引号但场景里使用了单引号字符串。文本字段包含转义引号导致正则匹配范围错误。翻译接口返回顺序和请求顺序不一致。场景文件编码不是 UTF-8读取时发生 UnicodeDecodeError。回写后 Unity 文件丢失 BOM或者 Godot 文件被自动格式化成 CRLF。每一类失败都要先在小样本上复现再改提取或回写逻辑不要直接全量重跑。9. 资源占用与性能观察这套方案是纯 CPU 批量任务不涉及 GPU 推理性能瓶颈主要在三个位置。9.1 场景文件解析Godot 和 Unity 场景文件通常是几 MB 到几十 MB正则解析在普通笔记本上运行很快单个文件解析时间以秒为单位。真正慢的是超大型场景几十 MB 的 YAML 文件反复做正则替换内存占用会上升。处理这类文件时建议把文本读取、替换、写出分开不要一次性把所有场景文件全读进内存。9.2 翻译 API 调用大部分耗时在网络请求。100 条文本用批量接口一次调用可能只要几秒如果用单条接口逐条调用按 0.2 秒一条计算100 条就是 20 秒。所以优先用支持数组参数的批量接口这是最有效的性能优化手段。9.3 缓存命中率第一次跑完全量翻译后后续新增语言或增量场景时缓存命中率越高处理时间越短。如果两次只改了一句话新语言的全量翻译依然要重新调用接口这一点在预算评估时要考虑进去。9.4 观察方法运行批量任务时用任务管理器或top观察 CPU 和内存。CPU 会短暂拉高内存取决于场景文件大小如果内存占用持续增长说明代码里有累积引用需要检查是不是把读取出来的大字符串一直保留在变量里。10. 常见问题与排查方法问题现象可能原因排查方式解决方案UnicodeDecodeError场景文件编码不是 UTF-8用文本编辑器查看文件编码读取时指定编码Unity 文件用utf-8-sig翻译后场景打不开回写时破坏了 YAML 结构用 diff 工具对比原文件和回写文件回写前先做格式校验确保只替换字符串字面量部分文本没有翻译正则没有匹配到单引号或多行字符串打印提取结果检查遗漏文本格式扩展正则或改用引擎提供的资源解析工具翻译结果顺序错乱接口返回顺序与请求顺序不一致打印返回的原始 JSON按接口文档调整解析逻辑增加原文与译文配对校验接口返回 429请求频率超过 QPS 限制检查日志中的 HTTP 状态码增加 sleep 间隔降低并发数长文本被截断接口对单条文本长度有限制查看请求返回的截断内容按长文本阈值拆分成多条后分别翻译回写后 Unity 中文乱码文件 BOM 丢失或编码不是 UTF-8用十六进制查看文件头统一使用utf-8-sig写回缓存在脚本中断后失效缓存只在全部完成后写入检查是否每个文件后立即写缓存改为每处理一个文件保存一次缓存翻译后 UI 文字溢出英文转中文后文本长度增加在引擎里直接观察运行效果预留文本空间或启用字体自适应、文本裁剪、多语言字表11. 最佳实践与使用建议11.1 工程化地管理场景文件场景文件是美术和策划每天都在改的文件直接在原文件上做翻译替换非常危险。建议场景文件先复制到一个独立目录脚本只处理副本人工确认后再把翻译结果合并回正式工程。整个过程用版本管理工具记录变更出现问题时可以随时回滚。11.2 构建“原文-译文”双层校验翻译接口并不可靠到可以直接信任。在大规模批处理后应该写一个独立的校验脚本对比每个场景文件中还有没有残留的源语言关键词。如果原文包含特定敏感标识或功能 flag这部分文本必须强制跳过不能进翻译流程。11.3 在缓存中维护术语一致性同一个词在不同场景里出现例如“攻击”“确认”“背包”如果一次一次调用翻译接口结果可能不一致。解决方案很简单缓存先查原文命中的直接复用已有译文。只要第一次翻译时人工校正术语后续所有场景都会自动沿用同一套译法。11.4 可视化回写前先做引擎内验证不要等几十个场景全部回写完再打开引擎看结果。先挑一个典型场景导回引擎跑一段完整流程确认没有加载错误、没有文字乱码、没有功能按键文案错位。通过后再执行全量回写。11.5 合规与授权提醒使用在线翻译服务传输游戏文本要确认文本内容不包含用户隐私、未公开的商业策划内容、未授权第三方版权素材。如果你的游戏还在保密开发期建议使用私有化部署的翻译模型或签署过保密协议的商用翻译服务。发布多语言版本前核对目标地区的文化禁忌和字体授权确保目标语言字库有合法商用授权。12. 总结与下一步这套工作流最值得尝试的点是把“翻译游戏场景”从手工操作变成了可重复执行的脚本流程。提取、翻译、回写三个环节彻底分开以后你可以替换任何一层换翻译供应商、加新语言、调整提取规则都不影响其他模块。最先应该验证的是你自己的场景文件格式确认m_Text和text ...的提取正则能覆盖项目里的真实文本。最容易踩的坑是回写时破坏场景结构所以务必先在副本上跑再进引擎验证。后续可以继续扩展的方向包括接入本地运行的翻译模型、增加术语表强制替换、把批量任务做成 Web 管理界面、接入游戏本地化平台。对独立游戏来说这套方案已经能把多语言版本的生产时间从几天压缩到半天以内。如果现在手头就有带大量文本的场景文件建议先复制一个副本按文章里的模板跑一遍提取看看能提出来多少条字符串这比继续纠结工具选型更有价值。
