CLI 故障排查

排查并解决文件选择、基线、收集和目录问题,无需先删除有用的状态信息。

诊断故障时,请备好已安装的版本、执行的命令、工作目录、错误信息和受影响的路径。分享日志前,请隐去凭据:启动和故障诊断信息可能包含原始 argv。

未匹配到源文件 #

找到距离当前目录最近的 .lingo/config.json。在嵌套目录中执行命令时,可能会使用上级目录中的项目。请先检查 include,再检查 pattern,因为即使包含规则为空,也会覆盖后者。排除规则仅对各自的条目生效;其他条目仍可能选中同一个文件。

请使用受支持的匹配器语法(如 docs/en/**/*),为 shell 模式加上引号,并确认是否支持相应的文件后缀。YAML 需要显式指定 yaml、yaml-root-key 或 yaml-openapi;Android XML 需要指定 android。对于 .txt、.csv 或 .properties 文件,模式必须以对应的扩展名结尾,或使用 "format": "txt"、"format": "csv" 或 "format": "properties";docs/en/**/* 这类宽泛的模式会跳过这些文件,而 txt、csv 或 properties 条目会跳过所有扩展名不匹配的文件。显式指定格式并不意味着支持所有扩展名。

输出位置不正确 #

查看路径推导警告,并将目标位置与应用加载器使用的位置进行对比。如果未识别出源语言区域对应的路径段,请定义 targetPath 和 sourceRoot,不要依赖插入语言区域的回退机制。确保目标文件不在源文件扫描范围内,并检查路径冲突。

仅移动文件不会更新基线。XCStrings 按设计使用一个共享的源目录,并非常见的按语言区域分别存放的布局。请参阅输出路径。

选项未生效 #

未知的根级或文件级键会触发警告,并被忽略。请检查拼写,确认所选处理器实际支持哪些选项。目录路径设置不会更新推送匹配模式;提取和检查操作也会各自独立地将源语言区域默认设为 en。

本地评分使用可执行程序 lingo.config.ts,而不是项目 JSON。用于 JSON 的保护选项不一定适用于 Markdown 或其他格式。

缺少基线产物 #

Lockfile 哈希所指向的上一份源产物必须存在于本地或服务器上。请检查指定条目,并恢复已知正确的字节内容或一致的基线。不要编造哈希,也不要清空整个 Lockfile 来掩盖错误。

缺少状态信息时,普通的首次推送会存储源文件的字节内容;缺失的普通目标文件则需要回填。Lockfile 与缓存说明了该操作需要哪条记录。

拉取操作报告冲突 #

运行 lingo pull --dry-run,查看系统如何决定是否写入。如果目标文件与服务器输出、推送时保存的字节内容以及 Lockfile 哈希均不一致,写入就会被阻止。提交该文件不会改变比较结果。

请保留并整合修改内容,或恢复到已知版本;只有在明确要替换内容时,才选择强制操作。不要在 push --wait 执行期间编辑目标文件,因为它不会像拉取操作那样重新检查冲突。

任务失败或尚未完成 #

查看各目标的错误信息,区分待处理、审核中、失败和输出缺失的情况。运行失败时,push --wait 和拉取操作会先写入已完成的文档,再以非零退出码退出;请核实状态和实际文件。

当所有未完成的目标都在等待人工审核时,push --wait 和拉取操作会停止等待,并给出提示。所有语言区域均已完成的文档可以收集;审核者完成审核后,请再次运行 lingo pull。再次推送并不能解除审核等待。

如果运行失败,请修正错误信息指出的问题,再重新执行适合该任务的命令。对于普通的源文件更新,请保持源文件不变并保留基线,然后使用 lingo push --wait。对于缺失的目标文件,请先确保现有目标文件均已更新,再按照添加语言重新执行缺失文件回填。仅为请求重试,无需修改源文件、使用强制标志或删除状态信息。

推送操作会打印所提交或重新关联的作业 ID。如果之前的推送尚未收集,且请求未变,推送操作会复用该请求:仍在运行的作业保留原 ID,失败的作业则由新作业替代。请保留失败作业的 ID,并确认下次打印的 Job 行显示了不同的 ID。这只能说明已提交新作业,并不代表翻译成功:请检查各目标的结果、获取输出并审核差异。在 --wait 执行期间,请保持本地目标文件不变;如果需要保护本地修改,请分别执行推送和带冲突检查的拉取操作。

如果已安装的客户端仍返回同一个失败作业,请停止重复提交,并发送邮件至 support@lingo.dev。请提供 CLI 版本、已移除敏感信息的命令、旧运行 ID 和返回的运行 ID、源文件修订版本、受影响的语言区域和路径、时间戳,以及已隐去敏感信息的错误信息。邮件中不要包含凭据、私有源文本或原始凭据文件。调查故障期间,请保留本地运行指针和 Lockfile。

删除运行指针并不是请求重新翻译的可靠方法。推送尚未收集时,指针保存着用于防止重复提交的请求标识。如果找不到运行记录,请检查所用机器、项目根目录的绝对路径,以及是否有另一次推送替换了指针。

目录检查失败 #

提取时,请使用与检查时相同的语言区域和路径。删除孤立条目前,先查看动态调用或解构调用的警告。只有当 files 模式匹配源目录时,才会报告目标文件缺失;否则,请对照预期的语言区域检查现有文件。

仅清理确实要删除的条目,重新生成声明,再运行检查和应用构建。status 已移至检查操作;内部服务名称不是可执行命令。

删除任何内容之前 #

清除会预览目标文件的删除操作。文件和语言区域筛选条件会将删除范围限定为所选目标及其 Lockfile 条目;不带筛选条件的清除操作会删除整个 Lockfile。共享的 XCStrings 目录会被跳过。只有在确实要删除内容时,才使用清除操作。大多数恢复任务只需针对具体问题进行修正,同时保留已认可的措辞和可恢复的状态信息。