先对齐语言码再跑合成——YoVoice 多语言配置的先后

一上来就调 YoVoice 合成，最容易踩的坑不是模型本身，而是语言码和语音包对不上：请求里写的是语言名称或习惯简写，语音包目录里却是另一套标识，结果要么报找不到音色，要么合成出夹杂口音的音频，等到发现问题时整批任务已经跑完，只能改配置重跑。稳妥的处理顺序通常是：先查清配置文件里语言码的真实写法，再按语言码筛选可用语音包，然后固定文本侧的编码、换行与标点，接着先用单语言跑通一条最小链路，最后固化输出格式与命名规则后再扩到多语言。这套顺序的价值在于，任何一步出问题都能定位到具体环节，而不是在整批失败后靠猜。

YoVoice 多语言配置应按“语言码写法 → 语音包可用性 → 文本编码与标点 → 单语言跑通 → 输出命名”推进。适用场景是首次接入或新增语种；操作动作是每一步都留下可复查的配置和日志；验证方式是单条最小命令能出音频且语种正确；风险边界是具体字段名、目录结构随版本不同，需要结合环境确认后再批量执行。

查清配置文件里语言码的写法

第一件要确认的事，是配置里语言码字段到底长什么样。不同工具对语言标识的写法差异很大：有的用 zh-CN 这类“语言-地区”形式，有的只认 zh，有的写成下划线形式 zh_CN，还有的直接用自定义短码。如果用“中文”“Chinese”“普通话”这类语言名称去匹配语音包，通常匹配不上，因为语音包索引一般按码值建立，不按自然语言名匹配。

可以先在配置文件里找到语言相关字段，确认取值来源，而不是凭经验填。查看方式通常有两种：直接检索配置文件中的关键字，或调用一次列出可用语言的接口/命令看它返回的写法。

# 在配置目录里定位语言字段，看实际写法
grep -rniE "lang|locale|language" ./conf | head -n 40

# 若工具提供列举能力，直接看它认可的语言码清单
yovoice-cli list-languages

# 留意大小写、连字符与下划线差异
yovoice-cli list-languages | tr 'A-Z' 'a-z' | sort

判读要点：清单里出现的形式就是“标准写法”，配置里照抄即可；如果清单只有 zh-CN 而配置写 zh_CN，先按清单修正，再谈其他参数。这里的命令名和子命令只是示意，替换成你所在版本实际提供的入口。需要结合环境确认的是：同一语言在不同语音包厂商下的码值可能并不通用，不要拿 A 包的语言码去套 B 包。

按语言码筛选可用语音包

语言码对上了，不等于目标语言真有可用音色。多语言场景常见的情况是：语言码在列表里，但对应的语音包没下载、没授权，或只提供了单一音色。这时合成请求能发出去，返回却是默认音色或直接失败。

检查方式通常是两份材料对照：语音包目录的实际内容，和配置/接口返回的语音包列表。

# 看语音包目录里实际安装了哪些包
ls -1 ./voices

# 按目标语言码过滤，确认是否存在匹配项
ls -1 ./voices | grep -i 'zh-CN'

# 若提供列举命令，看每个语音包归属的语言码与音色名
yovoice-cli list-voices `--lang` zh-CN

判读要点：目录名或列表项里应能同时看到语言码和音色标识；只有语言码没有音色名，说明音色维度还需要单独指定；列表为空则说明该语言当前没有可用包，应先去补齐语音包或换一个已安装的相近语种，而不是在请求里硬填。音色是否“听起来对”，建议用后面单语言验证时的一小段样本音频判断，而不是只信字段名。

固定文本侧的编码、换行与标点

语言和语音包都对了，输入文本仍可能让结果偏离预期：文件编码不是 UTF-8 时，中文或其他非 ASCII 字符可能变成乱码喂进合成；换行符混用（\r\n 与 \n 并存）会让按行切分的批处理多出空行或截断句子；全角、半角标点混排则可能影响停顿位置。这些都不是语音包的问题，但表现上很像“音色不对”。

# 检查文件编码
file -i input.txt

# 检查是否含 CRLF 换行
file input.txt
grep -c $'\r' input.txt

# 统一成 UTF-8 与 LF（先备份原文件）
iconv -f UTF-8 -t UTF-8 input.txt -o input.utf8.txt
dos2unix input.utf8.txt

判读要点：file -i 应显示 charset=utf-8；grep -c $'\r' 返回 0 说明没有 CRLF 残留。标点方面，建议在同一批任务里统一使用一套标点风格，别一半用中文句号、一半用英文句点，这样后续比较不同批次结果时变量更少。文本侧这些检查建议在跑批量之前做完，因为改文本往往意味着整批要重来。

先单语言跑通再扩到多语言

前面三步是静态检查，这一步是动态验证。做法是先只跑一个语言、一条短文本，确认输出音频的语种、音色、时长都合理，再把同一套配置扩到多语言。这样一旦出问题，能明确是语言码、语音包、文本还是输出设置的问题，而不是多语种混在一起排查。

# 单语言最小命令（字段名按实际版本替换）
yovoice-cli synth \
  `--lang` zh-CN \
  `--voice` female-01 \
  `--text-file` sample.txt \
  `--out` ./out/zh-CN-sample.wav

# 扩到多语言时，主要改动点是语言码与语音包两处
# 其余参数（采样率、输出目录、命名规则）保持一致

扩到多语言时的改动点集中在两处：`--lang` 换成目标语言码，`--voice` 换成该语言下实际存在的音色。如果原命令带采样率、音量、语速这类参数，建议先保持不变，等所有语言都能出音频后再统一调，避免同时改多个变量。验证方式很直接：每新增一个语种，先单独跑一条，确认输出存在且格式可打开，再并入批量。

固化输出格式与命名规则

多语言批量最容易在后期环节返工：输出文件全堆在一个目录、文件名看不出语种和音色、格式不统一导致剪辑软件要逐个转码。建议在配置阶段就把输出路径、格式和命名模板定下来，让批量结果可以直接进后期。

# 输出目录按语种分层，命名模板带上语种、音色与序号
# 示例结构：
# out/zh-CN/female-01/0001.wav
# out/en-US/male-02/0001.wav

yovoice-cli synth \
  `--lang` zh-CN \
  `--voice` female-01 \
  `--text-file` sample.txt \
  `--out-dir` ./out/{lang}/{voice}/ \
  `--format` wav \
  `--name-template` "{index:04d}"

# 跑完后清点产物，确认每个语种都有输出
find ./out -type f -name '*.wav' | sort

命名模板里建议至少包含语种和序号，音色如果能进目录名就更好；格式选 wav 还是 mp3，要看后期流程是否需要无损，别在合成阶段就做有损压缩。验证方式是跑完一批后用 find 或目录浏览确认文件数量与语种目录对得上，再抽查几个文件的音频参数是否一致。这套规则一旦固定，后续新增语种只是复制目录结构，不需要重新设计输出。