Troubleshooting

Section anchor links do not work in translated docs

A link like [label](other.md#section-id) may open the correct translated file but fail to scroll to the intended heading — or jump to the wrong section. The #… fragment no longer matches any heading id in that locale.

Common causes:

• Source headings never had explicit anchor ids; the site derives slugs from visible heading text, which changes after translation.
• You renamed a heading in source but the preceding <a id="…"></a> line is missing or still has the old id.
• Anchor links use a #… fragment guessed from English words instead of the id write-heading-ids would generate.

Fix

1. Run ai-i18n-tools write-heading-ids on your source .md / .mdx (same docs[] / contentPaths as translate-docs). By default it inserts <a id="slug"></a> before each ATX heading, or refreshes an existing anchor when the heading text no longer matches the current slug. For Docusaurus MDX comment ids, use --slug-style mdx-comment.
2. Point anchor links at those ids — e.g. [setup](guide.md#first-run) where #first-run matches the anchor line above the target heading, not a slug inferred from the English title alone.
3. Re-run translate-docs (or sync --force-update) so every locale copy includes the updated anchor lines.

Use --dry-run on write-heading-ids first to preview changes. See Anchor links for the full pattern.

Image or asset links 404 in translated docs

A markdown link or ![alt](url) works in English but returns 404 in translated copies — often because the URL still points at the source-locale folder or an English-only static path.

Fix

1. Confirm your asset layout matches your docsOutput.style (flat vs doc-system). See Link rewriting and Images & Screenshots.
2. Add or adjust docsOutput.postProcessing.regexAdjustments to swap locale segments or bridge absolute /img/… paths. For flat layout, remember the flat link rewriter runs before regexAdjustments — match patterns against the already-prefixed URL.
3. Ensure locale-specific asset files exist at the paths the rewritten markdown references (translate-docs rewrites URLs but does not copy raster files).

Hindi, Arabic, CJK, or Cyrillic output is romanized (Latin letters)

Some models translate the meaning but write the result in Latin/Roman letters (for example Hindi as Namaste instead of नमस्ते). Bare hi means Devanagari; use hi-Latn only when you want romanized Hindi.

Fix

1. Confirm the locale code matches the script you want (hi vs hi-Latn, zh-Hans vs zh-Hant, sr vs sr-Latn).
2. Re-run translation so wrong-script cache rows are rejected: translate-ui --force for UI strings, or translate-docs --check-cache / sync --check-cache (file-level skip is bypassed only for locales with an expected script; valid segment cache is still reused). --force-update reprocesses every locale.
3. If a model keeps failing the script check, add a localeModels entry for that locale so a stronger model is tried first — see Providers and models.