语言选择¶

Electron 语言选择器显示代表性旗帜（或地球图标）、本地化名称、本地原生名称（当与本地化名称不同时）以及语言代码。搜索会匹配所有名称和代码、代表性旗帜的国家名称/代码以及旗帜表情符号，忽略大小写和重音符号，并在本地运行，无输入延迟或网络请求。所选值保留为项目和请求中现有的规范语言名称。葡萄牙语以葡萄牙语（巴西）和葡萄牙语（葡萄牙）的形式提供；保存为纯「Portuguese」的值显示为葡萄牙语（巴西），且不会被重写。当所选模型无法渲染所选变体的口音时，选择器底部会给出提示（引擎的 rendered_dialects）；请参阅支持的语言。

截图使用测试夹具的模型元数据：支持的语言被列出，不支持的语言则隐藏在显示所有语言之后。

选择与无障碍¶

弹出窗口会根据需要自适应为一列、两列或三列。自动选项和最多四个最近启用的选项（位于最近下）排在列表前面，随后是所选模型支持的语言。不支持的语言折叠在单个显示所有语言行（带计数）后面；该行是一个普通列表行，因此 Up/Down 可以到达它，Enter 可以展开或折叠它而不关闭弹出窗口。搜索仍可找到不支持的语言，它们排在支持的匹配项之后，并附有针对该模型的禁用说明。保存的不支持选择会保持该部分展开，以便当前值保持可见。同一语言的地域或文字变体（例如葡萄牙语（巴西）和葡萄牙语（葡萄牙））会分组在该语言名称之下。最近选项仅保存在本设备上，绝不会覆盖模型支持。

打开时聚焦于搜索。Up/Down 按阅读顺序在启用的选项和「显示所有语言」行之间导航；Enter 选择，Escape 取消。Alt+Left/Right 也可导航，并遵循 RTL；普通的 Left/Right 和 Home/End 保留其原生的文本编辑行为。IME 确认不会选择语言。关闭后恢复焦点；Tab 退出弹出窗口。列表会公开所选/禁用状态、结果计数、位置和总大小。虚拟化使活动选项即使在滚动到视口之外时也保持挂载。

模型兼容性¶

Clone、Design、Stories、Audiobook、批量配音和配音片段输出选择器使用所选 TTS 模型声明的语言名称。源录音、翻译目标和现有配音轨道导航保持独立于 TTS；共享搜索界面也改善了这些选择器。保存的不兼容语言会保持可见并带有警告，而不是被静默更改。在克隆/设计、长篇、批量和配音合成之前会检查已知不兼容的本地请求；引擎侧的验证仍具有权威性。

有限引擎使用其适配器的语言声明。原生 OmniVoice 适配器使用捆绑的语言词汇表。每个精选的 MLX-Audio 模型都会声明其模型卡中记录的语言（MLXAudioBackend.CURATED_MODEL_LANGUAGES，来源见代码）：CSM、Dia、Chatterbox 和 MeloTTS-English 仅支持英语，Qwen3-TTS 涵盖 10 种语言，OuteTTS 1.0 涵盖 23 种。同一列表驱动选择器和合成保护。Kokoro 从已安装的包中读取其表格（包括 dict(...) 声明），而无需导入 MLX 或加载权重；如果无法读取这些表格，则回退到其声明的集合。只有自定义的 MLX-Audio 仓库被明确标记为未知，这并不表示普遍支持。加载与发现失败有单独的标签。选择语言不会下载或切换任何模型。自动（Auto）保留每个引擎现有的自动/默认行为；它不会为另一种语言添加支持。

维护与验证¶

选择器的虚拟化菜单位于渲染器中（features/clone/language-menu.tsx）；排序以及最近/支持/折叠行布局是 lib/language-search.ts 中的纯函数，并带有单元测试。经典的共享 SearchableSelect 对其其他消费者保持不变。language-codes.json 镜像 LANG_NAME_TO_ID，并由后端一致性测试守护。面向用户的标签同时存在于两个 Electron 语言环境树中。

运行选择器、语言选项、TTS 语言和受影响的生成单元测试；在 HF_HUB_OFFLINE=1 和空缓存的情况下运行 tests/test_engine_language_options.py；进行 Electron 类型检查和语言环境检查。electron/tests/language-picker-smoke.mjs 检查浏览器布局、旗帜、折叠的不支持行、焦点返回、禁用选择、活动选项挂载，并使用英语/德语/阿拉伯语以及桌面平台桥接测试夹具来测量过滤效果。将 VOICESTUDIO_UI_URL 设置为冒烟测试服务器，并可选设置 PLAYWRIGHT_CHANNEL。这些桥接测试夹具不能替代原生操作系统或手动屏幕阅读器测试。

部分配音重新生成会在渲染器中检查所选片段。后端在合成之前验证其最终的本地渲染集合，包括因缓存缺失、损坏或来自不兼容时间格式而被提升的片段。

MeloTTS English 将其可选的 g2p_en 包保留为手动依赖项；它不会被捆绑。生成在缺少该前提条件时会报告。请在同一 Python 环境中显式安装其 NLTK 数据：python -m nltk.downloader averaged_perceptron_tagger averaged_perceptron_tagger_eng cmudict。生成在导入文本前端之前会检查本地资源，并且绝不会下载缺失的 NLTK 数据。现有的 NLTK 搜索目录和应用 nltk_data 目录会被复用。

Qwen3-TTS 会接收其上游适配器所需的完整语言名称，包括当用户选择 ISO 代码或区域别名时。

引擎渲染和预热会持有驻留租约，包括配音和批量调用。切换引擎会推迟卸载任何仍在渲染的模型；退役模型在其最后一次渲染完成后才会被释放。

当 TorchCodec 不可用时，音频解码会优先使用 libsndfile，并使用已安装的 FFmpeg 处理 M4A 和 AAC 等压缩容器格式。声道数和采样率会被保留；解码过程不会下载任何工具。

OuteTTS 参考预处理会复用此解码器，之后再进行降混和重采样，以匹配其编解码器的速率。

FFmpeg 回退方案将压缩流的暂存和已解码音频各限制在 512 MiB，并在复制时检查临时存储空间是否至少还有 64 MiB 可用。如果输出过大，它会直接拒绝，而不会返回截断的片段。