docs: 30 links in the ja/ko/zh pages point at ref/** pages that were never translated (English tree is clean)

Aperta Adatta ai principianti
  • Qualcosa non va?
#5,534 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
78/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Ambito
documentation

Direzione di ricerca

Inizia dai file Markdown localizzati indicati nell’issue: le voci di docs/ja, docs/ko e docs/zh per tools.md, testing.md, agents.md, mcp.md, sessions.md e sandbox/guide.md. Verifica ogni link relativo rispetto alle pagine inglesi in docs/ref/ e al percorso dell’immagine condivisa; correggi i link non funzionanti seguendo gli approcci suggeriti nell’issue. Il lavoro è completato quando tutti e 30 i link vengono risolti correttamente nel sito localizzato.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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:

  1. 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.
  2. Image only, clearly a typo: docs/{ja,ko,zh}/sandbox/guide.md should use ../../assets/images/harness_with_compute.png — that is what the English page effectively resolves to (docs/sandbox/guide.md → docs/assets/images/...).
  3. 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.

Lingua principale
Python
Stelle
30.5k
Fork
5k
Merge medio
19h 30m
PR unite (30g)
129

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di openai/openai-agents-python

Tutte le issue di openai/openai-agents-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.