docs: 30 links in the ja/ko/zh pages point at ref/** pages that were never translated (English tree is clean)
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 2/5
- 预计耗时
- 1-3 小时
- 新手友好度
- 78/100
- Issue 类型
- 文档
- 描述清晰度
- 描述清楚
- 活跃度
- 活跃
调研方向
从 issue 中提到的本地化 Markdown 文件开始：检查 docs/ja、docs/ko 和 docs/zh 中对应 tools.md、testing.md、agents.md、mcp.md、sessions.md 和 sandbox/guide.md 的条目。对照英文 docs/ref/ 页面和共享图片路径检查每个相对链接；按照 issue 建议的方法修复失效链接。本地化网站上的 30 个链接都能正确解析即为完成。
由索引模型根据 Issue 内容生成。
描述
Summary
The Japanese, Korean and Chinese pages link to ref/** pages (and one image) that do not exist under their locale directory, so those links 404 on the localized site while the English pages work.
30 links: docs/ja 10, docs/ko 10, docs/zh 10. Ten distinct targets, nine pages and one image:
| target as written | exists in English tree | missing under |
|---|---|---|
ref/lifecycle.md |
docs/ref/lifecycle.md ✅ |
docs/{ja,ko,zh}/ref/ |
ref/mcp/manager.md |
docs/ref/mcp/manager.md ✅ |
同上 |
ref/memory/openai_conversations_session.md |
✅ | 同上 |
ref/testing.md |
✅ | 同上 |
ref/realtime/testing.md |
✅ | 同上 |
ref/voice/testing.md |
✅ | 同上 |
ref/extensions/experimental/codex/codex_tool.md |
✅ | 同上 |
ref/extensions/experimental/codex/thread_options.md |
✅ | 同上 |
ref/extensions/experimental/codex/turn_options.md |
✅ | 同上 |
../assets/images/harness_with_compute.png |
docs/assets/images/harness_with_compute.png ✅ |
docs/{ja,ko,zh}/assets/images/ |
Concrete example (docs/ja/agents.md:303):
コールバックの全機能については、[Lifecycle API リファレンス](ref/lifecycle.md)を参照してください。
Relative to docs/ja/agents.md that resolves to docs/ja/ref/lifecycle.md, which does not exist — docs/ja has 28 entries and no ref/ directory, while docs/ref/ contains the whole API reference. The same holds for ko and zh.
Per-file breakdown (10 links each, same targets in all three locales):
| file | links |
|---|---|
tools.md |
3 (codex_tool, thread_options, turn_options) |
testing.md |
3 (ref/testing, ref/realtime/testing, ref/voice/testing) |
agents.md |
1 (ref/lifecycle) |
mcp.md |
1 (ref/mcp/manager) |
sessions.md |
1 (ref/memory/openai_conversations_session) |
sandbox/guide.md |
1 (../assets/images/harness_with_compute.png) |
Why CI does not catch it
mkdocs.yml validates links as warnings, not errors, and i18n uses docs_structure: folder without fallback_to_default, so a localized page that points at a file which only exists in the default-language tree simply produces a build warning and a dead link:
validation:
omitted_files: warn
absolute_links: warn
unrecognized_links: warn
anchors: warn
Suggested fix
Any of these, in increasing effort:
- Smallest, per-link: for the nine
ref/**links, point at the English page on the built site (/openai-agents-python/ref/lifecycle/, etc.). One-line change per link, no translation needed. - Image only, clearly a typo:
docs/{ja,ko,zh}/sandbox/guide.mdshould use../../assets/images/harness_with_compute.png— that is what the English page effectively resolves to (docs/sandbox/guide.md→docs/assets/images/...). - Proper fix: add the translated
ref/**pages under each locale (translation pipeline), which also removes the warning noise.
How this was found
Relative-link resolution over all 522 markdown files in the repository (docs/**), comparing each ](path) against the file system, then filtering out the documented exceptions (links into src/, external URLs, images under a locale's own assets/). The English tree reports 0 broken links with the same check, which is what separates "translation lag" from "the checker is wrong".
Why an issue and not a PR
CONTRIBUTING.md says pull requests are limited to repository collaborators and explicitly includes documentation changes, so I am reporting it here. If you would like the mechanical part (option 2, the three image paths) as a patch from a maintainer, it is three lines.
- 主要语言
- Python
- 星标
- 30.5k
- 派生
- 5k
- 平均合并
- 19 小时 30 分钟
- 30 天内合并 PR
- 129
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
openai/openai-agents-python 的其他 Issue
-
难度 1/5 1 小时以内 新手友好度 88/100
openai/openai-agents-python#5529 ·
维护者通常 1 天内回复
-
难度 1/5 1 小时以内 新手友好度 88/100
openai/openai-agents-python#5498 ·
维护者通常 1 天内回复
-
Preserve wire aliases when converting Responses output items to input可能已有人在做 @LVsarff 于 3 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 62/100
openai/openai-agents-python#5477 · 2 条评论 ·
维护者通常 1 天内回复
-
Voice: default sentence splitter never splits Chinese/Japanese, so TTS waits for the whole reply未关闭
难度 2/5 1-3 小时 新手友好度 78/100
openai/openai-agents-python#5475 · 1 条评论 ·
维护者通常 1 天内回复
-
tool_choice naming a function tool called web_search, file_search, mcp, etc. selects the built-in tool instead可能已有人在做 @LVsarff 于 3 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 70/100
openai/openai-agents-python#5472 · 3 条评论 ·
维护者通常 1 天内回复
查看 openai/openai-agents-python 的全部 Issue
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 88/100
didi/helixharness#18 ·
-
request-theme
难度 1/5 1 小时以内 新手友好度 78/100
LizardByte/ThemerrDB#9883 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 75/100
NousResearch/hermes-agent#149885 ·
维护者通常 1 天内回复
-
Set cache_ok = True on GUID TypeDecorator to enable SQLAlchemy query caching可能已有人在做 @patelshivani2283-lab 今天认领。 未关闭
难度 1/5 1 小时以内 新手友好度 91/100
fedora-infra/anitya#2157 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 84/100
Project-MONAI/MONAI#9258 ·
维护者通常 3 天内回复