已关闭
ops-ras 英文文档导航链接语言错配 #50
KaranocaVe创建于  23 天前关闭于  6 天前
KaranocaVe
KaranocaVe
23 天前 创建

ops-ras 英文文档导航链接语言错配

结论

固定公开源码 cann/ops-ras@e43ac41176f9c57fd0d38db8f53354016b90f8b2 的英文文档入口有 18 个相对链接指向中文 README 或 docs/zh/ 页面。对应英文页面已经在同一提交的 README_en.md、docs/QUICKSTART_en.md 和 docs/en/ 中存在。链接目标大多可以打开,但英文用户会被带到中文内容,两个 README 锚点还使用了中文标题。

问题不是死链:固定提交的文件树同时包含中文和英文目标。问题是英文导航没有遵守仓库已经建立的中英文页面配对,导致英文入口的语言上下文被切换。

固定源码与精确位置

仓库:cann/ops-ras

源码提交:e43ac41176f9c57fd0d38db8f53354016b90f8b2

文档位置 当前相对目标 对应英文目标
README_en.md:34 docs/zh/install/quick_install.md docs/en/install/quick_install.md
README_en.md:49 docs/QUICKSTART.md docs/QUICKSTART_en.md
README_en.md:50 docs/README.md docs/README_en.md
README_en.md:54 docs/zh/install/dir_structure.md docs/en/install/dir_structure.md
docs/README_en.md:44 zh/install/compile.md en/install/compile.md
docs/README_en.md:45 zh/invocation/quick_op_invocation.md en/invocation/quick_op_invocation.md
docs/README_en.md:46 zh/develop/aicore_develop_guide.md en/develop/aicore_develop_guide.md
docs/README_en.md:48 zh/debug/op_debug_prof.md en/debug/op_debug_prof.md
docs/README_en.md:54 zh/op_list.md en/op_list.md
docs/README_en.md:55 zh/op_api_list.md en/op_api_list.md
docs/README_en.md:61 zh/debug/cann_sim.md en/debug/cann_sim.md
docs/README_en.md:71 zh/context/basic_concept.md en/context/basic_concept.md
docs/README_en.md:72 zh/install/build.md en/install/build.md
docs/QUICKSTART_en.md:7 ../README.md ../README_en.md
docs/QUICKSTART_en.md:275 ../README.md#学习教程 ../README_en.md#learning-tutorials
docs/QUICKSTART_en.md:275 ../README.md#相关信息 ../README_en.md#related-information
docs/en/invocation/quick_op_invocation.md:6 ../../zh/op_list.md ../../en/op_list.md
docs/en/invocation/quick_op_invocation.md:6 ../../zh/op_api_list.md ../../en/op_api_list.md

事实证据

  • 固定提交的文件树包含上述 14 个唯一英文目标:根级 README_en.md、docs/QUICKSTART_en.md、docs/README_en.md,以及 docs/en/{context,debug,develop,install,invocation} 下对应页面。
  • 固定提交的英文根 README 在第 47 行和第 52 行分别使用 Learning Tutorials、Related Information 标题;固定提交对应的 GitCode 页面渲染出 learning-tutorials、related-information 两个锚点。中文锚点 学习教程、相关信息 不属于英文页面标题。
  • 固定提交的英文文档由提交 e6f47ca7ed19ad09f08ffc2a9fe99b8fa123412b 成批加入,包含上述英文入口和详细页面;这证明 docs/en/ 是有意提供的英文文档树,而不是缺少英文替代页面。
  • 基线扫描命中 18 个链接引用并以退出码 1 失败;应用补丁后同一扫描命中 0 个,所有对应英文目标存在。

用户影响

英文用户从项目英文 README、英文文档目录、英文快速开始或英文算子调用指南继续导航时,会进入中文页面,无法保持预期的英文阅读路径;快速开始结尾的两个链接还无法按英文标题定位到对应章节。

最小修复边界

fix.patch 仅把上述 18 个相对目标改为已有英文页面,并将两个中文 README 锚点改为英文锚点。不改文档内容、源码、构建脚本或测试。docs/README_en.md:47 指向的 examples/fast_kernel_launch_example/README.md 是中英双语页面且没有独立英文副本,因此不将其作为错配修复;根 README 的中英文切换入口和外部官方中文链接也不在本案范围内。

去重

  • 同仓库已有安装文档 Issue 只处理 .run 安装命令缺少 --full,文件范围和根因均不同。
  • GitCode Issue #14 与 PR !81、!82 只新增根 README 的中英文切换入口,没有修正英文文档内部导航。
  • Issue #21、#24、#41、#42、#44、#45 及 PR !85、!109、!112 处理的是不存在的文件名、图片路径或锚点失效;本案的 18 个目标文件均存在,根因是语言目录选择错误。
  • Issue #8 与 PR !76 负责补齐英文文档集合,未覆盖补齐后英文入口仍指向中文页面的问题。

Validation

验证记录

在固定提交 e43ac41176f9c57fd0d38db8f53354016b90f8b2 上,14 个唯一英文目标文件均存在,英文 README 对应章节锚点为 learning-tutorials 和 related-information。

基线扫描发现 18 个指向中文页面或中文锚点的链接。应用补丁后,同一规则发现 0 个错配;git apply --check --whitespace=error-all、git diff --check 和 git apply --reverse --check --whitespace=error-all 均通过。

补丁只改动 4 个英文 Markdown 文件,不涉及源码、构建脚本或运行时行为。本案是文档链接与文件树的静态检查,不声称进行了 NPU 或 CANN 运行验证。

关联 PR: https://gitcode.com/cann/ops-ras/merge_requests/124

likedislike
KaranocaVeKaranocaVe
23 天前 关联了pull request:修正英文文档导航链接指向中文页面
KaranocaVeKaranocaVe
23 天前 修改了issue 的描述
yue-ma成员
22 天前 评论:

/assign @KaranocaVe

likedislike
CANN-robotCANN-robot成员
22 天前 将 KaranocaVe 设为负责人
CANN-robotCANN-robot成员
6 天前 关闭了 issue
CANN-robotCANN-robot成员
6 天前 添加了label:resolved