HarmonyOS6.1.1-AI字幕：切换语言时-如何判断问题在组件状态还是翻译结果-育师

我给 AI 字幕页加了“中文到英文”和“英文到中文”两个按钮后，第一次演示的场面有点尴尬：按钮颜色切过去了，页面也写着新的语言方向，可屏幕上没有一行新的英文或中文字幕。旁边的人问我，语言切换是不是没有生效。

我当时差点顺着这个问题去找翻译质量、语言包或者组件内部行为。回头看，这个方向一开始就错了。当前页面能确认的是配置有没有更新，不能从没有出现字幕文本反推出“翻译没工作”。真实字幕文本还依赖组件准备、麦克风授权、真实 PCM 输入，以及设备上的系统能力。它们没有同时满足时，页面静止是正常的，不是语言按钮的反证。

这篇只复盘这一个误判：为什么我已经把语言方向切成en-US -> zh-CN，却仍不能把“字幕看起来没变”写成语言设置失效，更不能把它写成翻译结果错误。

故障现场：两个状态都变了，文本仍为空

页面初始值是zh-CN到en-US，修订号从 1 开始。点击“英文到中文”时，按钮会变成选中颜色，顶部显示也会改成en-US -> zh-CN。我最初把这几个现象都当作“字幕应该立刻换语言”的前提，忽略了它们只是配置层的状态。

实际更新函数非常短：它没有写入任何字幕文字，也没有承诺产生翻译内容。它做的是保存新的源语言与目标语言，再递增configRevision。这个修订号很有价值，因为它给一次配置变化留下了可观察的编号，而不是只靠肉眼看按钮颜色。

private updateLanguage(sourceLanguage: string, targetLanguage: string): void { this.sourceLanguage = sourceLanguage; this.targetLanguage = targetLanguage; this.configRevision += 1; }

我在排查时先固定了一次操作：记录切换前的方向和修订号，点击一次，再记录切换后的值。只要sourceLanguage、targetLanguage和修订号三者一致变化，就能证明页面已提交了新的组件选项。至于屏幕上是否出现文字，是下一段输入路径的事情，不能抢在前面下结论。

这个流程图把当时混在一起的两件事拆开了。语言设置是否写入，落在 A 到 G；文本能否出现，取决于 H 之后。前者是当前代码可以直接观察的页面行为，后者不能靠按钮点击替代。

我最先查错的地方

第一轮，我盯的是字幕区域。它没有显示新语言文字，我就怀疑sourceLanguage和targetLanguage没有传给组件。实际上，页面通过buildOptions()每次构造AICaptionOptions，把当前两个字段交给AICaptionComponent。这说明选项来源不是写死的默认值。

private buildOptions(): AICaptionOptions { return { onPrepared: () => { /* 只记录组件准备状态 */ }, onError: (error: BusinessError) => { /* 只记录组件错误状态 */ }, sourceLanguage: this.sourceLanguage, targetLanguage: this.targetLanguage, fontSize: this.captionFontSize, fontColor: this.captionFontColor }; }

第二轮，我又把“组件没有显示文本”理解成“组件没有收到新配置”。这也不够严谨。组件的onPrepared和onError在页面里分别写入runtimeState，它们说明的是组件准备或报错的运行时状态；它们不是语言识别、翻译成功的回执。即使页面显示prepared，仍然只说明组件可以进入后续输入流程，不能凭空产生一段可当作结果的字幕。

第三轮才回到正确顺序：先核对配置修订号，再核对组件状态，随后才看麦克风和 PCM 输入。这样一来，“没看到文本”不再是一个模糊结论，而是能定位到某一段尚未发生的流程。

为什么修订号比按钮颜色可靠

按钮颜色是一个便利提示，但它不能告诉我这是不是一次新的配置提交。比如用户先选“中文到英文”，再重复点击同一按钮，颜色没有变化；若我只截按钮，无法区分是没有操作还是重复操作。configRevision则提供了一个单调递增的操作标识。

我把检查动作收紧成三步：先读取当前sourceLanguage -> targetLanguage和 revision；点击目标组合；再确认方向与 revision 是否符合预期。这里不需要制造一段测试音频，也不需要猜测翻译文本。页面本身已经有足够的信息证明“配置变了”。

这张图对应我后来使用的测试顺序。语言配置与运行时摘要并列展示，而不是让字幕区域承担所有判断。这样页面出现“等待 AICaptionComponent onPrepared”时，我知道该先解决准备状态；页面出现“麦克风未授权，未启动”时，我知道该处理授权；writeAudio次数为 0 时，我知道没有真实 PCM 写入。没有哪一项可以被“字幕文字没变”替代。

把误判改成可以落地的排查

我后来给自己留了一张很短的排查表。第一项是语言值：切换后是否确实从zh-CN -> en-US变为en-US -> zh-CN。第二项是 revision：是否加一。第三项是组件状态：waiting、prepared、failed不能混为一谈。第四项才是输入状态，例如麦克风是否已授予、PCM 是否正在写入。

这四项有先后，不是因为某项更重要，而是每项能回答的问题不同。语言值回答“我让组件采用哪种配置”；revision 回答“这次操作是否真的提交”；组件状态回答“组件是否准备好”；PCM 计数回答“是否存在真实音频供组件处理”。只有最后一个问题向前推进，字幕区才可能出现真实文本。

有一次我为了让页面“看起来完整”，想在切换语言后写一行“已切换为英文字幕”。这会让演示顺滑，却会让状态含义失真。它把配置确认伪装成了文本结果，也会让后续排查无法判断这行文字来自系统组件还是页面自己拼出来的。最后我没有加这种提示，而是把“按钮只更新组件选项，不生成识别或翻译结果”的边界保留在页面里。

修复落点不在字幕文案，而在状态分层

这次并没有给语言切换函数补一个“翻译”调用。正确的调整是让每一层在页面上都有独立位置：语言组合和修订号属于配置区；onPrepared、onError属于组件状态；麦克风授权、PCM 输入状态和writeAudio次数属于音频输入区。任何一层缺失，都应如实显示缺失，而不是借用字幕文案掩盖。

当真实麦克风开始工作时，回调才会把 PCM 数据交给控制器，并增加写入次数。这个计数可以证明页面确实在向组件提供实时输入；它仍不能说明识别内容或翻译内容正确。

private readonly audioDataCallback = (buffer: ArrayBuffer): void => { try { this.captionController.writeAudio({ data: new Uint8Array(buffer) }); this.pcmWriteCount += 1; this.audioInputState = '正在从真实麦克风写入 PCM'; } catch (error) { this.audioInputState = 'PCM 写入失败'; } };

我特别保留了“真实”这个限定。因为模拟一个递增的数字很容易，但那只能证明页面能改状态，不能证明音频路径存在。这里的计数应当和麦克风授权、音频采集器启动以及实际回调一起看，不能独立当成字幕结果。

我会怎样复测

复测第一组只做语言配置：从中文到英文切到英文到中文，记录两次方向和 revision。预期是方向对应按钮，修订号各增加一次，不要求字幕区域出现任何固定句子。

第二组只做组件准备：在不启动麦克风时观察waiting、prepared或failed。预期是页面只报告真实回调状态，不用“已翻译”填补空白。

第三组才在已准备且已授权的设备上启动真实麦克风，观察 PCM 状态、写入次数和最后写入时间。即便此时有字幕显示，我也只把它作为真实设备上的观察记录；本篇不对语言识别准确率、翻译质量或文本内容作结论。

这次复盘让我改掉了一个习惯：看到屏幕没有变化时，先不要问“结果为什么不对”，而是逐层问“我到底改变了什么、组件已经准备到哪里、真实输入是否存在”。语言按钮能做的事情很明确，超过它的范围就不该由它背锅。

一次没有声音的复现，让我看清了误判

为了把问题从主观感受里拿出来，我做了一次刻意安静的复现。设备放在桌面上，既不申请麦克风权限，也不点击启动 PCM 输入。此时字幕区没有任何文字，运行时摘要中的输入状态也保持“未启动”。我先记下初始配置：zh-CN -> en-US、修订号 1。随后点击“英文到中文”，配置区显示为en-US -> zh-CN，修订号变为 2，按钮选中态也变化。

这次复现非常有用，因为我从头到尾没有制造“应该听到一句话”的期待。没有音频进入，页面没有文本，本来就符合条件；但配置值和修订号发生变化，说明语言操作已经完成。以前我会把这两件事压缩为一句“切换后没效果”，现在会记录成两个独立事实：配置已更新；真实文本尚无输入条件，不作判断。

然后我反过来再做一遍：不修改语言方向，只重复打开页面、观察运行时状态。这时如果onPrepared尚未回调，摘要会写 waiting；如果回调失败，会写 failed 和错误信息。无论是哪种情况，revision 都不会自动变化。这个反向操作让我确认，revision 是用户配置的操作记录，不是组件健康度指标。把它当成“组件已重新准备”的证据，同样会走偏。

我还特别注意到，语言按钮的按钮色只依据sourceLanguage是否匹配某一个值。也就是说，它表达的是当前页面选择，不是“上一次音频已经按该语言处理”。当语言方向为中文到英文时，按钮高亮；切成英文到中文，另一颗按钮高亮。这个视觉反馈足够服务选择操作，却不应承载运行时结论。

不能用静态文案补足缺失的结果

排查期间，有人建议在切换语言后在页面下方显示“目标语言：中文”或“目标语言：英文”，让用户能立刻感到变化。作为配置提示，这没有问题；问题在于提示很容易在后续迭代中被写成“中文字幕已开启”或“英文翻译已开启”。前者仍可理解为展示偏好，后者已经暗示输出存在。

我最终采用的判断方式是：任何一句能被读成“系统已经说出了什么”的文案，都不能由语言按钮单独产生。配置区只陈述sourceLanguage、targetLanguage和修订号；运行时区只陈述waiting/prepared/failed、回调次数与时间；输入区只陈述麦克风和 PCM。这样，即使页面暂时空白，用户也能从状态中理解哪里没有推进，而不是把空白归因到翻译。

这点在自动化测试时尤其重要。如果测试脚本只点击语言按钮再截图字幕区域，结果会极不稳定：有的设备没有输入，有的设备未准备，有的环境不能使用相关能力。反过来，断言两个语言字段和 revision 则不依赖外界声音，也不要求任何系统回调。把可控断言放在配置层，把真机观察保留给运行时层，测试报告就不会把环境差异写成代码失败。

处理快速切换时，我只相信最后一次配置

还有一个小场景让我重新审视 revision。连续点“中文到英文”“英文到中文”“中文到英文”时，用户真正关心的是当前停在哪一种方向，而不是中间每次点击有没有让字幕立刻闪一下。页面状态会保留最后一次 source/target 组合，修订号则把三次配置写成连续的变化。

我没有试图根据 revision 推测每一次旧配置是否都被组件完整处理。那需要真实的组件回调与输入时序，而当前页面没有为此提供文本级记录。revision 的职责更单纯：帮助排查者确认最后一次配置不是旧值。若问题发生在连续点击之后，先记录最终方向与最后 revision，再观察组件是否准备，而不是拿先前的屏幕印象去判断。

这个原则也避免了另一个错误：把 configRevision 增加解释成“语言包重新加载成功”。代码中它只是数字递增，没有下载、加载或结果回调相关逻辑。写复盘时把它描述为配置版本，比使用带有运行意味的词准确得多。

按层次记录，排查才不会绕回原点

我现在会把一次问题记录写成四行。第一行是操作，例如“点选英文到中文”；第二行是配置，例如“source=en-US，target=zh-CN，revision=4”；第三行是组件摘要，例如“preparedCount=0，状态 waiting”；第四行是输入摘要，例如“麦克风未请求，writeAudio=0”。四行都来自页面已有字段，没有任何一行替代另一行。

一旦未来真机上出现字幕，记录方式也不需要改变。只是在第四行之后补充“观察到组件可见内容”，并把内容是否与目标语言一致留给专门的真实设备测试。这样不会因一次成功观察倒过来弱化此前的边界，更不会让一张截图承担配置、输入和文本质量三种不同结论。

在这个页面里，空白不是一个可以被随手填掉的缺陷描述。它可能是开关关闭、组件等待、权限未授予、采集未启动，或仅仅是环境没有声音。把语言状态单独立起来后，我能更早停止无效排查，也能更诚实地说明本次到底看到了什么。