Solução de problemas

Links âncora de seção não funcionam em documentos traduzidos

Um link como [label](other.md#section-id) pode abrir o arquivo traduzido correto, mas falhar ao rolar até o título pretendido — ou saltar para a seção errada. O fragmento #… não corresponde mais a nenhum título id nessa localidade.

Causas comuns:

• Os títulos de origem nunca tiveram IDs de âncora explícitas; o site gera slugs a partir do texto visível do título, que muda após a tradução.
• Você renomeou um título na origem, mas a linha <a id="…"></a> anterior está ausente ou ainda possui o ID antigo.
• Os links de âncora usam um fragmento #… adivinhado a partir de palavras em inglês, em vez do ID que write-heading-ids geraria.

Correção

1. Execute ai-i18n-tools write-heading-ids no seu .md / .mdx de origem (mesmo docs[] / contentPaths que translate-docs). Por padrão, ele insere <a id="slug"></a> antes de cada título ATX ou atualiza uma âncora existente quando o texto do título não corresponde mais ao slug atual. Para IDs de comentários MDX do Docusaurus, use --slug-style mdx-comment.
2. Aponte os links de âncora para esses IDs — por exemplo, [setup](guide.md#first-run) onde #first-run corresponde à linha de âncora acima do título de destino, não um slug inferido apenas do título em inglês.
3. Execute novamente translate-docs (ou sync --force-update) para que cada cópia de localidade inclua as linhas de âncora atualizadas.

Use --dry-run em write-heading-ids primeiro para visualizar as alterações. Consulte Links âncora para o padrão completo.

Links de imagem ou ativo retornam 404 em documentos traduzidos

Um link Markdown ou ![alt](url) funciona em inglês, mas retorna 404 em cópias traduzidas — geralmente porque o URL ainda aponta para a pasta do idioma de origem ou para um caminho estático somente em inglês.

Correção

1. Confirme se o layout do seu ativo corresponde ao seu docsOutput.style (plano vs. sistema de documentos). Consulte Reescrita de links e Imagens e capturas de tela.
2. Adicione ou ajuste docsOutput.postProcessing.regexAdjustments para trocar segmentos de localidade ou fazer a ponte entre caminhos /img/… absolutos. Para layout plano, lembre-se de que o reescritor de link plano é executado antes de regexAdjustments — combine padrões com o URL já prefixado.
3. Certifique-se de que os arquivos de ativos específicos da localidade existam nos caminhos referenciados pelo Markdown reescrito (translate-docs reescreve URLs, mas não copia arquivos raster).

A saída em hindi, árabe, CJK ou cirílico é romanizada (letras latinas)

Alguns modelos traduzem o significado, mas escrevem o resultado em letras latinas/romanas (por exemplo, hindi como Namaste em vez de नमस्ते). hi puro significa Devanagari; use hi-Latn apenas quando quiser hindi romanizado.

Correção

1. Confirme se o código de localidade corresponde ao script desejado (hi vs hi-Latn, zh-Hans vs zh-Hant, sr vs sr-Latn).
2. Execute a tradução novamente para que as linhas de cache de script incorretas sejam rejeitadas: translate-ui --force para strings da IU, ou translate-docs --check-cache / sync --check-cache (a ignorância em nível de arquivo é ignorada apenas para localidades com um script esperado; o cache de segmento válido ainda é reutilizado). --force-update reprocessa todas as localidades.
3. Se um modelo continuar falhando na verificação de script, adicione uma entrada localeModels para essa localidade para que um modelo mais forte seja tentado primeiro — consulte Provedores e modelos.