Skip to content

Fehlerbehebung ​

Ein Link wie [label](other.md#section-id) öffnet möglicherweise die korrekte übersetzte Datei, scrollt aber nicht zum gewünschten Überschriftselement – oder springt zum falschen Abschnitt. Das #…-Fragment entspricht keinem Überschrifts-id mehr in diesem Gebietsschema.

Häufige Ursachen:

  • Quellüberschriften hatten nie explizite Anker-IDs; die Seite leitet Slugs aus dem sichtbaren Überschriftstext ab, der sich nach der Übersetzung ändert.
  • Sie haben eine Überschrift in der Quelle umbenannt, aber die vorhergehende <a id="…"></a>-Zeile fehlt oder enthält noch die alte ID.
  • Ankerlinks verwenden ein #…-Fragment, das aus englischen Wörtern erraten wurde, anstatt der ID, die write-heading-ids generieren würde.

Behebung

  1. Führen Sie ai-i18n-tools write-heading-ids auf Ihrer Quell- .md / .mdx aus (gleiche docs[] / contentPaths wie translate-docs). Standardmäßig fügt es <a id="slug"></a> vor jeder ATX-Überschrift ein oder aktualisiert einen vorhandenen Anker, wenn der Überschriftentext nicht mehr mit dem aktuellen Slug übereinstimmt. Für Docusaurus MDX-Kommentar-IDs verwenden Sie --slug-style mdx-comment.
  2. Verweisen Sie Ankerlinks auf diese IDs – z. B. [setup](guide.md#first-run), wobei #first-run mit der Ankerzeile über der Zielüberschrift übereinstimmt, nicht mit einem Slug, der allein aus dem englischen Titel abgeleitet wurde.
  3. Führen Sie translate-docs (oder sync --force-update) erneut aus, damit jede Lokalisierungskopie die aktualisierten Ankerzeilen enthält.

Verwenden Sie zuerst --dry-run auf write-heading-ids, um Änderungen in der Vorschau anzuzeigen. Siehe Ankerlinks für das vollständige Muster.

Ein Markdown-Link oder ![alt](url) funktioniert auf Englisch, gibt aber in übersetzten Kopien einen 404-Fehler zurück – oft, weil die URL immer noch auf den Ordner der Quellsprache oder einen nur englischen statischen Pfad verweist.

Behebung

  1. Bestätigen Sie, dass Ihr Asset-Layout mit Ihrem docsOutput.style übereinstimmt (flach vs. Dokumentensystem). Siehe Link-Umschreibung und Bilder & Screenshots.
  2. Fügen Sie docsOutput.postProcessing.regexAdjustments hinzu oder passen Sie es an, um Gebietsschema-Segmente auszutauschen oder absolute /img/…-Pfade zu überbrücken. Bei einem flachen Layout denken Sie daran, dass der flache Link-Rewriter vor regexAdjustments ausgeführt wird – passen Sie Muster an die bereits präfixierte URL an.
  3. Stellen Sie sicher, dass sprachspezifische Asset-Dateien unter den Pfaden existieren, auf die das umgeschriebene Markdown verweist (translate-docs schreibt URLs um, kopiert aber keine Rasterdateien).

Hindi-, Arabisch-, CJK- oder Kyrillisch-Ausgabe wird romanisiert (lateinische Buchstaben) ​

Einige Modelle übersetzen die Bedeutung, schreiben das Ergebnis aber in lateinischen/römischen Buchstaben (zum Beispiel Hindi als Namaste anstelle von नमस्ते). Bloßes hi bedeutet Devanagari; verwenden Sie hi-Latn nur, wenn Sie romanisiertes Hindi wünschen.

Behebung

  1. Stellen Sie sicher, dass der Locale-Code mit der gewünschten Schrift übereinstimmt (hi vs. hi-Latn, zh-Hans vs. zh-Hant, sr vs. sr-Latn).
  2. Führen Sie die Übersetzung erneut aus, damit Cache-Zeilen mit der falschen Schrift abgelehnt werden: translate-ui --force für UI-Strings oder translate-docs --check-cache / sync --check-cache (das Überspringen auf Dateiebene wird nur für Locales mit einer erwarteten Schrift umgangen; der gültige Segment-Cache wird weiterhin wiederverwendet). --force-update verarbeitet jedes Locale erneut.
  3. Wenn ein Modell die Schriftprüfung wiederholt nicht besteht, fügen Sie einen localeModels-Eintrag für dieses Locale hinzu, damit zuerst ein stärkeres Modell ausprobiert wird – siehe KI-Modelle.

Veröffentlicht unter der MIT-Lizenz.