Zweisprachige Dokumentation ausgerichtet halten
Öffentliche Benutzerhandbücher werden durch relative Pfade gepaart:
docs/en/<relative-path>
docs/ja/<relative-path>
Englisch wird unter / veröffentlicht; Japanisch unter /ja/. Japanisch bleibt
die praktische Autorenquelle für neue Produkterklärungen, aber eine Bearbeitung in
beiderlei Sprache darf nicht stillschweigend ihr Gegenstück mit unterschiedlichem
Verhalten, anderen Befehlen, anderen Verantwortlichkeitsgrenzen, anderen Warnungen
oder anderer Navigation hinterlassen.
Geltungsbereich
Wende diesen Workflow auf index.md und guide/**/*.md unterhalb beider Sprachverzeichnisse an.
docs/en/reference/ ist absichtlich nur auf Englisch. Interne Architektur,
Entscheidungen, Repository-, Mitwirkenden- und Vorwärtstestdokumente außerhalb der
beiden Sprachverzeichnisse sind keine Übersetzungspaare.
Arbeitsablauf
- Untersuche die angeforderte Änderung und den aktuellen Git-Diff. Identifiziere jede betroffene öffentliche Seite und ihr Gegenstück mit dem gleichen relativen Pfad.
- Lies beide vollständigen Seiten. Wenn japanischer Inhalt erstellt, bearbeitet oder auf Lesbarkeit überprüft wird, lies auch die japanische Stilreferenz. Wenn die Bearbeitung das Produktverhalten, Befehle, Pfade oder Verantwortlichkeiten ändert, überprüfe die aktuelle Quelle oder die akzeptierte Entscheidung, anstatt eine Annahme zu übersetzen.
- Bewahre Bedeutung, Informationsarchitektur, Beispiele, Warnungen und Linkziele, schreibe aber für jedes Publikum eine natürliche Dokumentation, anstatt Satz für Satz zu übersetzen. Bearbeite beide Gegenstücke, wenn sich Bedeutung oder Informationsstruktur ändern. Bei einer rein japanischen Formulierungsverbesserung überprüfe das englische Gegenstück, erfinde aber keine englische Bearbeitung, wenn dessen Bedeutung und Struktur bereits übereinstimmen.
- Wenn ein Gegenstück nicht existiert, erstelle es. Wenn eine Seite absichtlich sprachspezifisch ist, bestätige, dass sie außerhalb des gepaarten Geltungsbereichs liegt, oder erhalte eine explizite Entscheidung, sie zurückzustellen; melde die Zurückstellung und ihren Nachverfolgungsort. Rufe die zweisprachige Änderung nicht für abgeschlossen, solange die Abweichung lediglich unerwähnt bleibt.
- Bei einer Verschiebung oder Entfernung wende die gleiche relative Pfadänderung auf beide
Bäume an und aktualisiere
mkdocs.yml, eingehende Links, die Mitwirkendenanleitung sowie alle öffentlichen URLs, die in Code oder Tests eingebettet sind.
Überprüfung
Führe vom Repository-Stammverzeichnis aus:
python -m mkdocs build --strict
git diff --check
Bestätige, dass die generierten englischen und japanischen Seiten unter den entsprechenden
Pfaden existieren und dass ihre Sprachauswahl-Links aufeinander verweisen. Wenn eine
offentliche URL ein CLI-Vertrag ist, aktualisiere auch ihre Quelle, gezielten Tests und
die akzeptierte Entscheidung, führe dann den gezielten Test und python scripts/check_decisions.py
aus.
Melde die untersuchten und geänderten Seitenpaare, jedes absichtlich nach semantischem Vergleich unverändert gelassene Gegenstück, jede andere Ausnahme sowie die Überprüfungsergebnisse.