Links âncora

Quando docsOutput.style = "flat", a saída reescreve caminhos relativos entre páginas para cada localidade (guide.md → guide.de.md). Links âncora — a forma inline usual do markdown com um # após o caminho — saltam para uma seção dentro do arquivo de destino:

Read the [installation checklist](setup.md#first-run) before you deploy.

Aqui, o destino do link é setup.md, e #first-run é a âncora: deve rolar até o título correto dentro desse arquivo.

Por que os links âncora precisam de atenção

• rewriteRelativeLinks corrige o nome do arquivo para cada localidade (setup.md → setup.de.md).
• Muitos renderizadores derivam o slug # do texto visível do título. Após a tradução, os títulos diferem por localidade, então um slug gerado automaticamente pode mudar enquanto o link reescrito ainda pode dizer #first-run — ou seu âncora em inglês #… não corresponde mais ao slug que o renderizador cria a partir do título traduzido.
• Resultado: os leitores chegam ao arquivo certo, mas na linha errada, ou o navegador não encontra um título correspondente.

O que fazer

Sites Docusaurus (preferencial)

Na documentação Docusaurus (docsOutput.style = "docusaurus"), prefira os IDs de cabeçalho nativos do Docusaurus em vez de ai-i18n-tools write-heading-ids:

1. Adicione um ID explícito na linha do cabeçalho com o sufixo {#…} do Docusaurus, por exemplo, ## TLS configuration {#tls-configuration}. Durante a translate-docs, apenas o texto visível do cabeçalho é traduzido — o sufixo {#tls-configuration} é preservado em todos os locais.
2. Execute docusaurus write-heading-ids a partir da raiz do seu projeto Docusaurus (geralmente pnpm run write-heading-ids quando conectado em package.json) para adicionar ou atualizar os sufixos {#…} nos cabeçalhos que não os possuem. Execute novamente após renomear os cabeçalhos para que os IDs antigos correspondam aos títulos atuais.

Aponte seus links âncora de markdown para esses IDs estáveis, por exemplo, [label](other.md#tls-configuration), onde o fragmento corresponde ao sufixo {#…} — não um slug adivinhado apenas a partir de palavras em inglês. Veja examples/docusaurus-docs para documentos confirmados que usam esse padrão.

Outros layouts (flat, Starlight, VitePress, etc.)

Quando você não está no Docusaurus, ou precisa de âncoras HTML em vez de sufixos {#…}:

1. Execute ai-i18n-tools write-heading-ids no seu código-fonte .md / .mdx antes de translate-docs (mesmo docs[] / contentPaths de costume). Ele insere âncoras HTML explícitas na linha anterior a cada título, de modo que os valores id sejam compartilhados por todas as cópias traduzidas. Execute novamente após renomear títulos para que IDs de âncora obsoletos sejam atualizados e correspondam ao título atual.
2. Aponte seus links âncora do markdown para esses IDs estáveis, por exemplo, [label](other.md#section-id), onde section-id corresponde à âncora escrita pela ferramenta — não apenas uma suposição baseada em palavras em inglês.

Exemplo

Sufixo {#…} do Docusaurus

docs/overview.md:

See [TLS setup](security.md#tls-configuration) for certificate steps.

docs/security.md (fonte em inglês):

## TLS configuration {#tls-configuration}

Your CA and cert steps…

Após translate-docs, o fragmento do link permanece #tls-configuration em todos os locais; apenas o texto do cabeçalho e o rótulo do link mudam:

Siehe [TLS-Einrichtung](security.md#tls-configuration) für die Zertifikatsschritte.

Âncoras HTML (write-heading-ids)

docs/overview.md:

See [TLS setup](security.md#tls-configuration) for certificate steps.

docs/security.md após write-heading-ids (simplificado):

<a id="tls-configuration"></a>

---

# TLS configuration

Your CA and cert steps…

Após translate-docs, caminhos de arquivos e âncoras #… permanecem alinhados em todos os arquivos de localidade, por exemplo:

Siehe [TLS-Einrichtung](security.de.md#tls-configuration) für die Zertifikatsschritte.

A âncora #tls-configuration é a mesma em todas as localidades porque o id é fixo na fonte; apenas o texto do título e o rótulo do link são traduzidos.

Se os links ainda falharem após a tradução, consulte Solução de problemas.