 翻译机制到自制语言文件的完整实践)
pyvideotrans 语言包开发指南从 tr() 翻译机制到自制语言文件的完整实践【免费下载链接】pyvideotransTranslate the video from one language to another and embed dubbing subtitles.项目地址: https://gitcode.com/gh_mirrors/py/pyvideotrans本文以 pyvideotrans 官方文档 docs/language.md「添加语言包」为核心系统讲解视频翻译软件界面本地化的原理与实操语言包如何被查找和加载、lang配置项与命令行参数如何强制指定界面语言、语言文件各字段的作用与修改规则并深入源码 videotrans/configure/_i18n.py 剖析翻译函数tr()的查找、格式化与降级行为。读完本文你可以独立完成一个新语言包的制作、验证与部署并理解每个配置项在底层代码中的真实作用。一、语言包的定位与查找机制pyvideotrans 的界面文本不硬编码在源码中而是全部放在语言文件里。官方文档规定的查找规则是软件启动时取系统当前语言代码文档给出的检测方式是locale.getdefaultlocale()[0]将其前 2 个字符转小写并拼接.json作为文件名到videotrans/language目录下搜寻文件存在则加载该语言不存在则显示英文界面如果在videotrans/set.ini文件中lang设置了值则以该值为默认语言代码否则以系统语言检测结果为准。先在控制台确认系统语言代码import locale locale.getdefaultlocale()[0]例如输出en_US按文档规则就创建en.json放入videotrans/language目录该文件即为语言文件。从源码看这一流程由 videotrans/configure/_i18n.py 中的_get_langjson_list()与_init_language()实现videotrans/configure/_i18n.pylru_cache(maxsizeNone) def _get_langjson_list(): lang_dir Path(f{ROOT_DIR}/videotrans/language) _SUPPORT_LANG {} if lang_dir.exists(): for it in lang_dir.glob(*.json): if it.stat().st_size 0: _SUPPORT_LANG[it.stem] it.as_posix() return _SUPPORT_LANGdef _init_language(settings): global defaulelang, _transobj SUPPORT_LANG _get_langjson_list() try: _lang os.environ.get(PYVIDEOTRANS_LANG, settings.lang) if not _lang or not SUPPORT_LANG.get(_lang) or not Path(SUPPORT_LANG.get(_lang)).exists(): _lang QLocale.system().name() except Exception: _lang en_US if _lang not in SUPPORT_LANG: _lang en_US if not settings.lang: settings.lang _lang settings.save() defaulelang _lang _transobj _get_transobj(defaulelang) return defaulelang, _transobj由此可以读出实际的语言代码确定优先级文档描述了其中两条代码中还有一条环境变量通路环境变量PYVIDEOTRANS_LANG命令行入口 sp.py 支持--lang参数帮助文本为Set the application language (e.g., en, zh)传入后写入该环境变量WebUI 入口 webui.py 同样会设置它。set.ini中的settings.lang即文档所说的lang配置项。它的默认值在 videotrans/configure/_app_settings.py 中为空字符串含义是未手动指定一旦_init_language()完成语言判定且settings.lang为空会把最终选中的语言代码回写并持久化settings.save()。系统语言QLocale.system().name()文档中locale.getdefaultlocale()的等价实现Qt 返回形如en_US、zh_CN的区域代码兜底en_US若最终语言代码在_SUPPORT_LANG即语言目录下非空.json文件的文件名主干集合中不存在回落到en_US对应文档所说的显示英文界面。需要特别注意的一个细节当前仓库内置的语言文件实际命名为 videotrans/language/en_US.json 和 videotrans/language/zh_CN.json而文档示例中使用的是两字符的en.json/zh.json。_SUPPORT_LANG以文件名主干去掉.json后的部分为键做精确匹配且空文件st_size 0会被跳过。因此自制语言包时文件名主干要么与最终确定的语言代码完全一致如en_US要么通过set.ini的lang或--lang显式指定同时文件不能为空否则会被查找逻辑直接忽略。二、用 lang 配置强制指定界面语言官方文档强调制作完成后确认符合正确的 json 格式然后放到 videotrans/language 目录下重启软件就会自动应用该语言。如果你制作的语言包和默认语言不同可通过设置set.ini中lang语言代码强制使用比如langzh将强制显示 zh.json 内容。其底层机制就是上述_init_language()中的settings.lang通路当lang有值且对应语言文件存在时_lang直接采用该值不再探测系统语言。由于语言对象_transobj在配置模块初始化阶段一次性加载完成videotrans/configure/config.py 中defaulelang, _transobj _init_language(settings)lang修改后必须重启软件才能生效。WebUI 的参数设置面板中lang一项的提示正是设置后需重启webui.py。命令行与 WebUI 场景下则有更直接的手段python sp.py --lang zhsp.py 会将cli_args.lang.lower()写入环境变量PYVIDEOTRANS_LANG它比set.ini具有更高优先级适合在不改动配置文件的情况下临时切换界面语言。三、语言文件结构四大字段的划分与当前仓库的实际形态官方文档规定语言文件是一个 JSON 对象最外层有 4 个字段{ translate_language: {}, ui_lang: {}, toolbox_lang: {}, language_code_list: {} }四个字段的职责分工如下原文档表述字段用途translate_language进度显示、错误提示、各种交互状态的文本ui_lang软件界面各个部件的显示名称toolbox_lang视频工具箱界面各个部件的显示名称language_code_list支持的语言显示名称界面语言下拉框中的文字对照当前仓库的语言文件videotrans/language/en_US.json、videotrans/language/zh_CN.json各约 1000 行、上千个翻译键可以推断项目后续把上述四个分类的键扁平化合并成了单一键值映射不再有嵌套的四个顶层字段。例如 zh_CN.json 中同时包含界面部件名Help: 帮助/关于(H)、状态与错误文本Dubbing succeeded {}failed {}: 配音成功{}失败{}类、工具箱文本以及语言显示名Simplified Chinese: 简体中文、zh-cn: Simplified Chinese等。这一演进不影响文档的操作原则但简化了制作方式新语言文件只需维护一层键: 值对象键覆盖四个分类即可。由于翻译函数tr()是按单层键查表见下一节制作语言包时可以直接复制现有的zh_CN.json或en_US.json将全部值替换为目标语言文本比按四个字段拆分管理更不容易出错。四、字段修改规则与 tr() 翻译函数行为4.1 字段名不可改只改字段值文档对每一类字段的修改要求完全一致字段名不要动将字段值改为相应语言的文本。原文档给出的各类字段示例如下translate_language状态与提示文本translate_language: { qianyiwenjian: The video path or name contains non ASCII spaces. To avoid errors, it has been migrated to , mansuchucuo: Video automatic slow error, please try to cancel the Video auto down option }ui_lang界面部件名称ui_lang: { SP-video Translate Dubbing: SP-video Translate Dubbing, Multiple MP4 videos can be selected and automatically queued for processing: Multiple MP4 videos can be selected and automatically queued for processing, Select video..: Select video.. }toolbox_lang工具箱部件名称toolbox_lang: { No voice video: 无声视频, Open dir: 打开目录, Audio Wav: 音频文件 }language_code_list语言显示名language_code_list: { zh-cn: Simplified Chinese, zh-tw: Traditional Chinese, en: English, fr: French, de: German, ja: Japanese, ko: Korean, ru: Russian, es: Spanish, th: Thai, it: Italian, pt: Portuguese, vi: Vietnamese, ar: Arabic, tr: Turkish, hi: Hindi }字段名即键的设计意味着键是程序内调用翻译时的固定标识包括英文短语、拼音键如qianyiwenjian、以及语言代码如zh-cn无论目标语言是什么键必须原样保留翻译的只是值。4.2 源码视角tr() 如何取词、降级与格式化翻译的运行时入口是 videotrans/configure/_i18n.py 中的tr()函数def tr(lang_key, *kw): global _transobj if not _transobj: _transobj _get_transobj(defaulelang) if not _transobj: return lang_key if isinstance(lang_key, list): str_list [t for t in [_transobj.get(it) for it in lang_key] if t] return ,.join(str_list) lang _transobj.get(lang_key) if not lang: return lang_key if not kw: return lang try: return lang.format(*kw) except IndexError: return lang三个关键行为直接影响语言包的制作质量缺失键静默降级为键本身_transobj.get(lang_key)取不到值时直接返回键字符串。也就是说如果你漏译了某个键界面上会显示该键的原始文本通常是英文而不会崩溃——这也是字段名不能动的原因它是程序定位文案的唯一锚点。支持str.format占位符传入额外参数时会执行lang.format(*kw)。因此翻译值中如果原文含{}占位符例如Dubbing succeeded {}failed {}、The role {} does not exist翻译时必须保留占位符且顺序一致否则运行时格式化失败会返回未格式化的原文。翻译对象加载失败的兜底_get_transobj()videotrans/configure/_i18n.py用json.loads读取语言文件若解析抛异常会把错误信息写入项目根目录的start_error.txt随后_transobj为空tr()全部回落为键本身——界面表现为英文键多为英文短语。所以文档反复强调确认符合正确的 json 格式一个多余的尾逗号就足以让整个语言包失效。实际使用示例可见主窗口标题的构造videotrans/mainwin/main_win.pyself.rawtitle f{tr(softname)} {VERSION} {tr(Documents)} pyvideotrans.com五、自制语言包完整实操步骤结合文档流程与源码约束完整步骤如下以制作de德语语言包为例确认语言代码。在控制台执行import locale locale.getdefaultlocale()[0]取输出的前 2 个字符小写拼接.json得到文件名如de.json。注意若希望程序在自动探测时也能命中文件名主干应与QLocale.system().name()返回的代码如de_DE一致用两字符名时建议在set.ini中显式langde强制指定。复制现有语言文件。当前仓库已有en_US.json、zh_CN.json两个语言文件直接复制后改名cp videotrans/language/en_US.json videotrans/language/de.json修改字段值。打开de.json保留全部键将值翻译为目标语言含{}占位符的值保留占位符语言显示名language_code_list对应的Simplified Chinese、en等键按目标语言习惯书写。校验 JSON 格式。可用如下命令验证语法避免start_error.txt式静默失效python -c import json; json.load(open(videotrans/language/de.json, encodingutf-8))部署并重启。文件放入videotrans/language目录后重启软件即自动应用若与默认语言不同在videotrans/set.ini中设置langde强制使用该语言包对应_init_language()中settings.lang优先级高于系统探测或通过命令行python sp.py --lang de临时指定。验证生效。启动后界面标题、按钮、进度提示等文案应全部切换若仍是英文优先检查文件名主干与语言代码是否匹配、文件是否为空、set.ini的lang值是否写对、JSON 是否存在语法错误并查看根目录有无start_error.txt。六、小结文档规则与源码实现的对应关系官方文档规则源码实现位置到videotrans/language目录下按文件名搜寻语言文件videotrans/configure/_i18n.py_get_langjson_list()跳过空文件locale.getdefaultlocale()[0]探测系统语言videotrans/configure/_i18n.py 中QLocale.system().name()兜底en_USset.ini的lang强制指定语言settings.lang默认空串见 videotrans/configure/_app_settings.py判定后回写持久化语言文件四大字段的分工当前仓库语言文件已扁平化为单层键值映射四类键合并存放于 videotrans/language/en_US.json、videotrans/language/zh_CN.json字段名不动、只改字段值tr()按键查表缺失时返回键本身videotrans/configure/_i18n.py确认 JSON 格式后放到目录并重启config.py初始化阶段一次性加载语言对象videotrans/configure/config.py故必须重启掌握以上机制后为 pyvideotrans 增加任何一种新语言界面本质上就是复制一个现有语言文件、翻译全部值、保持键与 JSON 语法严格合法再借助lang或--lang验证效果即可。【免费下载链接】pyvideotransTranslate the video from one language to another and embed dubbing subtitles.项目地址: https://gitcode.com/gh_mirrors/py/pyvideotrans创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pyvideotrans 语言包开发指南：从 tr() 翻译机制到自制语言文件的完整实践
pyvideotrans 语言包开发指南从 tr() 翻译机制到自制语言文件的完整实践【免费下载链接】pyvideotransTranslate the video from one language to another and embed dubbing subtitles.项目地址: https://gitcode.com/gh_mirrors/py/pyvideotrans本文以 pyvideotrans 官方文档 docs/language.md「添加语言包」为核心系统讲解视频翻译软件界面本地化的原理与实操语言包如何被查找和加载、lang配置项与命令行参数如何强制指定界面语言、语言文件各字段的作用与修改规则并深入源码 videotrans/configure/_i18n.py 剖析翻译函数tr()的查找、格式化与降级行为。读完本文你可以独立完成一个新语言包的制作、验证与部署并理解每个配置项在底层代码中的真实作用。一、语言包的定位与查找机制pyvideotrans 的界面文本不硬编码在源码中而是全部放在语言文件里。官方文档规定的查找规则是软件启动时取系统当前语言代码文档给出的检测方式是locale.getdefaultlocale()[0]将其前 2 个字符转小写并拼接.json作为文件名到videotrans/language目录下搜寻文件存在则加载该语言不存在则显示英文界面如果在videotrans/set.ini文件中lang设置了值则以该值为默认语言代码否则以系统语言检测结果为准。先在控制台确认系统语言代码import locale locale.getdefaultlocale()[0]例如输出en_US按文档规则就创建en.json放入videotrans/language目录该文件即为语言文件。从源码看这一流程由 videotrans/configure/_i18n.py 中的_get_langjson_list()与_init_language()实现videotrans/configure/_i18n.pylru_cache(maxsizeNone) def _get_langjson_list(): lang_dir Path(f{ROOT_DIR}/videotrans/language) _SUPPORT_LANG {} if lang_dir.exists(): for it in lang_dir.glob(*.json): if it.stat().st_size 0: _SUPPORT_LANG[it.stem] it.as_posix() return _SUPPORT_LANGdef _init_language(settings): global defaulelang, _transobj SUPPORT_LANG _get_langjson_list() try: _lang os.environ.get(PYVIDEOTRANS_LANG, settings.lang) if not _lang or not SUPPORT_LANG.get(_lang) or not Path(SUPPORT_LANG.get(_lang)).exists(): _lang QLocale.system().name() except Exception: _lang en_US if _lang not in SUPPORT_LANG: _lang en_US if not settings.lang: settings.lang _lang settings.save() defaulelang _lang _transobj _get_transobj(defaulelang) return defaulelang, _transobj由此可以读出实际的语言代码确定优先级文档描述了其中两条代码中还有一条环境变量通路环境变量PYVIDEOTRANS_LANG命令行入口 sp.py 支持--lang参数帮助文本为Set the application language (e.g., en, zh)传入后写入该环境变量WebUI 入口 webui.py 同样会设置它。set.ini中的settings.lang即文档所说的lang配置项。它的默认值在 videotrans/configure/_app_settings.py 中为空字符串含义是未手动指定一旦_init_language()完成语言判定且settings.lang为空会把最终选中的语言代码回写并持久化settings.save()。系统语言QLocale.system().name()文档中locale.getdefaultlocale()的等价实现Qt 返回形如en_US、zh_CN的区域代码兜底en_US若最终语言代码在_SUPPORT_LANG即语言目录下非空.json文件的文件名主干集合中不存在回落到en_US对应文档所说的显示英文界面。需要特别注意的一个细节当前仓库内置的语言文件实际命名为 videotrans/language/en_US.json 和 videotrans/language/zh_CN.json而文档示例中使用的是两字符的en.json/zh.json。_SUPPORT_LANG以文件名主干去掉.json后的部分为键做精确匹配且空文件st_size 0会被跳过。因此自制语言包时文件名主干要么与最终确定的语言代码完全一致如en_US要么通过set.ini的lang或--lang显式指定同时文件不能为空否则会被查找逻辑直接忽略。二、用 lang 配置强制指定界面语言官方文档强调制作完成后确认符合正确的 json 格式然后放到 videotrans/language 目录下重启软件就会自动应用该语言。如果你制作的语言包和默认语言不同可通过设置set.ini中lang语言代码强制使用比如langzh将强制显示 zh.json 内容。其底层机制就是上述_init_language()中的settings.lang通路当lang有值且对应语言文件存在时_lang直接采用该值不再探测系统语言。由于语言对象_transobj在配置模块初始化阶段一次性加载完成videotrans/configure/config.py 中defaulelang, _transobj _init_language(settings)lang修改后必须重启软件才能生效。WebUI 的参数设置面板中lang一项的提示正是设置后需重启webui.py。命令行与 WebUI 场景下则有更直接的手段python sp.py --lang zhsp.py 会将cli_args.lang.lower()写入环境变量PYVIDEOTRANS_LANG它比set.ini具有更高优先级适合在不改动配置文件的情况下临时切换界面语言。三、语言文件结构四大字段的划分与当前仓库的实际形态官方文档规定语言文件是一个 JSON 对象最外层有 4 个字段{ translate_language: {}, ui_lang: {}, toolbox_lang: {}, language_code_list: {} }四个字段的职责分工如下原文档表述字段用途translate_language进度显示、错误提示、各种交互状态的文本ui_lang软件界面各个部件的显示名称toolbox_lang视频工具箱界面各个部件的显示名称language_code_list支持的语言显示名称界面语言下拉框中的文字对照当前仓库的语言文件videotrans/language/en_US.json、videotrans/language/zh_CN.json各约 1000 行、上千个翻译键可以推断项目后续把上述四个分类的键扁平化合并成了单一键值映射不再有嵌套的四个顶层字段。例如 zh_CN.json 中同时包含界面部件名Help: 帮助/关于(H)、状态与错误文本Dubbing succeeded {}failed {}: 配音成功{}失败{}类、工具箱文本以及语言显示名Simplified Chinese: 简体中文、zh-cn: Simplified Chinese等。这一演进不影响文档的操作原则但简化了制作方式新语言文件只需维护一层键: 值对象键覆盖四个分类即可。由于翻译函数tr()是按单层键查表见下一节制作语言包时可以直接复制现有的zh_CN.json或en_US.json将全部值替换为目标语言文本比按四个字段拆分管理更不容易出错。四、字段修改规则与 tr() 翻译函数行为4.1 字段名不可改只改字段值文档对每一类字段的修改要求完全一致字段名不要动将字段值改为相应语言的文本。原文档给出的各类字段示例如下translate_language状态与提示文本translate_language: { qianyiwenjian: The video path or name contains non ASCII spaces. To avoid errors, it has been migrated to , mansuchucuo: Video automatic slow error, please try to cancel the Video auto down option }ui_lang界面部件名称ui_lang: { SP-video Translate Dubbing: SP-video Translate Dubbing, Multiple MP4 videos can be selected and automatically queued for processing: Multiple MP4 videos can be selected and automatically queued for processing, Select video..: Select video.. }toolbox_lang工具箱部件名称toolbox_lang: { No voice video: 无声视频, Open dir: 打开目录, Audio Wav: 音频文件 }language_code_list语言显示名language_code_list: { zh-cn: Simplified Chinese, zh-tw: Traditional Chinese, en: English, fr: French, de: German, ja: Japanese, ko: Korean, ru: Russian, es: Spanish, th: Thai, it: Italian, pt: Portuguese, vi: Vietnamese, ar: Arabic, tr: Turkish, hi: Hindi }字段名即键的设计意味着键是程序内调用翻译时的固定标识包括英文短语、拼音键如qianyiwenjian、以及语言代码如zh-cn无论目标语言是什么键必须原样保留翻译的只是值。4.2 源码视角tr() 如何取词、降级与格式化翻译的运行时入口是 videotrans/configure/_i18n.py 中的tr()函数def tr(lang_key, *kw): global _transobj if not _transobj: _transobj _get_transobj(defaulelang) if not _transobj: return lang_key if isinstance(lang_key, list): str_list [t for t in [_transobj.get(it) for it in lang_key] if t] return ,.join(str_list) lang _transobj.get(lang_key) if not lang: return lang_key if not kw: return lang try: return lang.format(*kw) except IndexError: return lang三个关键行为直接影响语言包的制作质量缺失键静默降级为键本身_transobj.get(lang_key)取不到值时直接返回键字符串。也就是说如果你漏译了某个键界面上会显示该键的原始文本通常是英文而不会崩溃——这也是字段名不能动的原因它是程序定位文案的唯一锚点。支持str.format占位符传入额外参数时会执行lang.format(*kw)。因此翻译值中如果原文含{}占位符例如Dubbing succeeded {}failed {}、The role {} does not exist翻译时必须保留占位符且顺序一致否则运行时格式化失败会返回未格式化的原文。翻译对象加载失败的兜底_get_transobj()videotrans/configure/_i18n.py用json.loads读取语言文件若解析抛异常会把错误信息写入项目根目录的start_error.txt随后_transobj为空tr()全部回落为键本身——界面表现为英文键多为英文短语。所以文档反复强调确认符合正确的 json 格式一个多余的尾逗号就足以让整个语言包失效。实际使用示例可见主窗口标题的构造videotrans/mainwin/main_win.pyself.rawtitle f{tr(softname)} {VERSION} {tr(Documents)} pyvideotrans.com五、自制语言包完整实操步骤结合文档流程与源码约束完整步骤如下以制作de德语语言包为例确认语言代码。在控制台执行import locale locale.getdefaultlocale()[0]取输出的前 2 个字符小写拼接.json得到文件名如de.json。注意若希望程序在自动探测时也能命中文件名主干应与QLocale.system().name()返回的代码如de_DE一致用两字符名时建议在set.ini中显式langde强制指定。复制现有语言文件。当前仓库已有en_US.json、zh_CN.json两个语言文件直接复制后改名cp videotrans/language/en_US.json videotrans/language/de.json修改字段值。打开de.json保留全部键将值翻译为目标语言含{}占位符的值保留占位符语言显示名language_code_list对应的Simplified Chinese、en等键按目标语言习惯书写。校验 JSON 格式。可用如下命令验证语法避免start_error.txt式静默失效python -c import json; json.load(open(videotrans/language/de.json, encodingutf-8))部署并重启。文件放入videotrans/language目录后重启软件即自动应用若与默认语言不同在videotrans/set.ini中设置langde强制使用该语言包对应_init_language()中settings.lang优先级高于系统探测或通过命令行python sp.py --lang de临时指定。验证生效。启动后界面标题、按钮、进度提示等文案应全部切换若仍是英文优先检查文件名主干与语言代码是否匹配、文件是否为空、set.ini的lang值是否写对、JSON 是否存在语法错误并查看根目录有无start_error.txt。六、小结文档规则与源码实现的对应关系官方文档规则源码实现位置到videotrans/language目录下按文件名搜寻语言文件videotrans/configure/_i18n.py_get_langjson_list()跳过空文件locale.getdefaultlocale()[0]探测系统语言videotrans/configure/_i18n.py 中QLocale.system().name()兜底en_USset.ini的lang强制指定语言settings.lang默认空串见 videotrans/configure/_app_settings.py判定后回写持久化语言文件四大字段的分工当前仓库语言文件已扁平化为单层键值映射四类键合并存放于 videotrans/language/en_US.json、videotrans/language/zh_CN.json字段名不动、只改字段值tr()按键查表缺失时返回键本身videotrans/configure/_i18n.py确认 JSON 格式后放到目录并重启config.py初始化阶段一次性加载语言对象videotrans/configure/config.py故必须重启掌握以上机制后为 pyvideotrans 增加任何一种新语言界面本质上就是复制一个现有语言文件、翻译全部值、保持键与 JSON 语法严格合法再借助lang或--lang验证效果即可。【免费下载链接】pyvideotransTranslate the video from one language to another and embed dubbing subtitles.项目地址: https://gitcode.com/gh_mirrors/py/pyvideotrans创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考