疑難排解

翻譯文件中區段錨點連結無法運作

像 [label](other.md#section-id) 這樣的連結可能會開啟正確的翻譯檔案，但無法捲動到預期的標題 — 或跳到錯誤的區段。#… 片段在該地區設定中不再符合任何標題 id。

常見原因：

• 來源標題從未有明確的錨點 ID；網站會從可見標題文字衍生縮寫，這在翻譯後會改變。
• 您重新命名了來源中的標題，但前面的 <a id="…"></a> 行遺失或仍是舊 ID。
• 錨點連結使用猜測自英文單字的 #… 片段，而非 write-heading-ids 會產生的 ID。

修正

1. 在您的來源 .md / .mdx 上執行 ai-i18n-tools write-heading-ids（與 translate-docs 相同的 docs[] / contentPaths）。預設情況下，它會在每個 ATX 標題之前插入 <a id="slug"></a>，或者在標題文字不再與目前的 slug 相符時重新整理現有的錨點。對於 Docusaurus MDX 註解 id，請使用 --slug-style mdx-comment。
2. 將錨點連結指向這些 id — 例如 [setup](guide.md#first-run)，其中 #first-run 與目標標題上方的錨點行相符，而不是僅從英文標題推斷出的 slug。
3. 重新執行 translate-docs（或 sync --force-update），以便每個語言環境副本都包含更新後的錨點行。

請先在 --dry-run 上使用 write-heading-ids 預覽變更。如需完整模式，請參閱錨點連結。

翻譯文件中圖片或資產連結出現 404 錯誤

Markdown 連結或 ![alt](url) 在英文版中有效，但在翻譯版本中卻會傳回 404 錯誤 — 這通常是因為 URL 仍指向來源語系資料夾或僅限英文的靜態路徑。

修正

1. 確認您的資產佈局與您的 docsOutput.style 相符（扁平式與文件系統）。請參閱連結重寫和圖片與螢幕截圖。
2. 新增或調整 docsOutput.postProcessing.regexAdjustments 以交換語系區段或橋接絕對 /img/… 路徑。對於扁平式佈局，請記住扁平式連結重寫器在 之前 執行 regexAdjustments — 根據已加前綴的 URL 匹配模式。
3. 確保語系特定的資產檔案存在於重寫後的 markdown 參考路徑中（translate-docs 重寫 URL，但不複製點陣圖檔案）。

印地語、阿拉伯語、中日韓或西里爾字母的輸出被羅馬化（拉丁字母）

某些模型會翻譯其含義，但以拉丁/羅馬字母書寫結果（例如將印地語寫成 Namaste 而非 नमस्ते）。單純的 hi 表示天城文；僅在您需要羅馬化印地語時才使用 hi-Latn。

修正

1. 確認地區代碼與您想要的書寫系統相符（hi 對 hi-Latn，zh-Hans 對 zh-Hant，sr 對 sr-Latn）。
2. 重新執行翻譯，以便拒絕書寫系統錯誤的快取列：UI 字串使用 translate-ui --force，或 translate-docs --check-cache / sync --check-cache（檔案層級的跳過僅對具有預期書寫系統的地區被繞過；有效的區段快取仍會被重用）。--force-update 會重新處理每個地區。
3. 如果模型持續未通過書寫系統檢查，請為該地區新增 localeModels 項目，以便優先嘗試更強大的模型 — 請參閱供應商與模型。