Skip to content

Seletor de idioma (languageListBlock) ​

Use docsOutput.postProcessing.languageListBlock quando os arquivos Markdown traduzidos devem incluir uma linha de links "Ler em outros idiomas" — um link por localidade, com valores href calculados em relação a cada arquivo de saída.

Este repositório o utiliza para README.md (saída simples em translated-docs/). Após translate-docs, cada cópia traduzida recebe um bloco atualizado; por exemplo, translated-docs/README.de.md links para arquivos de localidade irmãos em translated-docs/ e de volta para a fonte em inglês na raiz do repositório.

Requer docsOutput.style = "flat" (ou outro layout em que os arquivos de localidade irmãos possam ser acessados por caminho relativo). Consulte Layouts de saída. Primeira vez adicionando isso a um README de repositório: Adicionar i18n aos seus documentos README e Markdown.

1. Marque o bloco no Markdown de origem ​

Envolva o seletor de idiomas em HTML (ou quaisquer linhas) delimitadas pelos marcadores de substring start e end. Este repositório usa:

markdown
<small>**Read in other languages:** </small>
<small id="lang-list">[English (GB)](/pt-BR/) · [Deutsch](./README.de.md) · …</small>

O texto inicial do link é apenas um espaço reservado. translate-docs substitui toda a seção desde a primeira linha contendo start até a primeira linha posterior contendo end (marcadores dentro de blocos de código cercados são ignorados, portanto exemplos de configuração no mesmo arquivo não correspondem).

2. Configure o bloco ​

start e end são marcadores de substring arbitrários — não precisam ser <small id="lang-list"> / </small>. Escolha qualquer texto de abertura e fechamento que apareça apenas na seção do seletor de idiomas: outra tag HTML (<div class="lang-switcher"> … </div>), comentários HTML (<!-- lang-list --> … <!-- /lang-list -->) ou delimitadores apenas em markdown (por exemplo, uma linha **Languages:** até uma linha ---). Defina start e end na configuração para corresponder exatamente ao que você colocou no arquivo de origem.

Configuração raiz (ai-i18n-tools.config.json):

json
"postProcessing": {
  "languageListBlock": {
    "start": "<small id=\"lang-list\">",
    "end": "</small>",
    "separator": " · "
  }
}
CampoFunção
startSubstring que identifica a linha de abertura do bloco
endSubstring na linha de fechamento (pode ser a mesma linha que start quando ambos aparecem em uma linha)
separatorTexto entre os links [label](href) gerados (este repositório usa " · ")
labelOpcional: "local" (padrão) usa o endônimo de cada idioma do manifesto; "english" usa englishName

3. O que acontece em tempo de execução ​

  1. Extração — a fatia da lista de idiomas não é enviada para o modelo (translatable: false).
  2. Por arquivo traduzido — após a tradução de segmentos e a reescrita opcional de links simples, o postProcessing recria o bloco: um link Markdown por localidade, rótulos de ui-languages.json quando presentes (caso contrário, o catálogo mestre incluído; caso contrário, localeDisplayNames), caminhos relativos ao arquivo que está sendo escrito.
  3. Atualização da origem — no final de uma passagem de documentos translate-docs / sync, o mesmo bloco canônico é gravado de volta nos arquivos da localidade de origem em contentPaths para que a adição de uma localidade atualize o seletor no repositório sem precisar editar manualmente cada link. Esses arquivos são gravados em sourceLocale, que pode ser qualquer idioma.

Se um arquivo não tiver um bloco correspondente, a CLI registra um aviso (quando --verbose) e mantém o conteúdo inalterado.

4. Manifesto de rótulos ​

Para rótulos de endônimo (label: "local"), gere ou mantenha ui-languages.json via generate-ui-languages (escrito em languagesManifestPath, que é padrão para {ui.flatOutputDir}/ui-languages.json). A configuração docs-only deste repositório não tem pipeline de UI e não tem manifesto de projeto no disco, então os rótulos vêm do catálogo mestre embutido para sourceLocale + targetLocales.

5. Exemplos neste repositório ​

ExemploArquivos
Este pacote (README simples + site VitePress)ai-i18n-tools.config.json (bloco README: docsOutput.style = "flat"; bloco do site: docsOutput.style = "vitepress" + vitepressThemeCatalog)
README simples + documentos Docusaurusexamples/nextjs-app/ai-i18n-tools.config.json (segundo bloco: docsOutput.style = "flat"; primeiro bloco: docsOutput.style = "docusaurus")
Apenas documentos do Docusaurusexamples/docusaurus-docs/ai-i18n-tools.config.json (docsOutput.style = "docusaurus" + docusaurusCatalogDir)
Documentação VitePress (demonstração mínima)examples/vitepress-docs/ai-i18n-tools.config.json (docsOutput.style = "vitepress" + vitepressThemeCatalog)

A linha imediatamente antes de <small id="lang-list"> (por exemplo, **Read in other languages:**) é um segmento normal passível de tradução e é localizada em cada localidade de destino; apenas a linha de links dentro dos marcadores é regenerada literalmente, exceto por href e rótulos gerados pelo manifesto.

Páginas HTML ​

Documentos HTML simples usam um par diferente de comentários, <!-- ai-i18n:lang-list --> e <!-- ai-i18n:hreflang -->. A lista de idiomas pode ser de links ou um <select>, e as alternativas hreflang são gravadas no arquivo da localidade de origem, bem como em cada arquivo da localidade de destino. Consulte Páginas HTML.

Lançado sob a Licença MIT.