MDX

Traduza texto em MDX e propriedades selecionadas de componentes com valores literais, preservando as expressões, as importações e a estrutura dos componentes.

O MDX permite incluir componentes interativos num artigo, a par do texto. O processador de ficheiros mdx traduz o texto suportado e o conteúdo dos elementos filhos dos componentes, preservando a respetiva marcação. Selecione explicitamente as propriedades dos componentes com valores literais quando estas também contiverem texto visível para quem lê; as importações e as expressões não são executadas para identificar texto.

Separe o texto dos dados dos componentes #

Por exemplo, uma caixa de destaque tem um título visível e uma propriedade que define o seu comportamento:

mdx
import Callout from "./Callout";

## Delivery options {#delivery}

<Callout title="Delivery deadline" kind="warning">
  Confirm your address before checkout.
</Callout>

O título e o texto dos elementos filhos são conteúdo a traduzir. kind corresponde a dados do componente que devem permanecer inalterados. title só passa a ser conteúdo a traduzir quando é selecionado por uma regra para propriedades de componentes. Uma regra limitada a Callout e title é mais segura do que traduzir todos os atributos com esse nome em componentes sem relação entre si.

São suportadas propriedades cujos valores são cadeias de texto literais. Uma propriedade calculada por uma expressão não equivale a uma mensagem literal. As importações, as expressões JavaScript e os blocos de código ficam fora da extração normal de texto. A estrutura dos componentes tem de se manter compatível com o renderizador da aplicação.

Metadados iniciais e âncoras de títulos #

Por predefinição, o processador de ficheiros seleciona title e description nos metadados iniciais. Forneça uma seleção vazia para manter os metadados iniciais por traduzir. A seleção de um mapa ou de uma sequência inclui os respetivos descendentes escalares, pelo que deve escolher caminhos precisos, como seo.title, quando os campos de encaminhamento adjacentes tiverem de permanecer inalterados. Consulte a configuração da CLI para saber mais sobre translateFrontmatterFields e translateComponentProps.

As âncoras de títulos do Docusaurus, como {#delivery}, são protegidas quando o texto do título é alterado. O tratamento de âncoras reconhece a sintaxe das linhas de título fora dos blocos de código delimitados e mantém inalterados os segmentos identificadores dos URLs. Verifique o ID do título renderizado e as ligações que apontam para ele no seu site.

Atualizações e alinhamento #

A redação existente pode ser reutilizada quando as versões anteriores do texto de origem e da tradução têm unidades de texto e estruturas protegidas em linha correspondentes. Quando essa correspondência é ambígua, o processador pode rejeitar a reutilização. Mantenha as traduções aceites associadas à respetiva revisão do texto de origem, em vez de fornecer, sem indicação, um documento com uma estrutura sem relação com a original.

Verifique as propriedades selecionadas após a reconstrução, incluindo os rótulos visíveis fora do texto dos elementos filhos, e compile o resultado com o processador MDX da sua aplicação.

Configure a tradução de MDX #

A CLI infere mdx a partir de .mdx; o âmbito por chave não está disponível para este formato. Consulte a configuração da CLI ou o GitHub para conhecer as opções relativas aos ficheiros.

Verifique o componente renderizado #

Compile o MDX obtido com o processador que efetivamente utiliza e verifique, em conjunto, as propriedades dos componentes, as âncoras, as variáveis e os exemplos de código. A tradução de ficheiros MDX preserva um documento que contém JSX; já a extração de mensagens do React identifica chamadas suportadas no código-fonte da aplicação e gera catálogos. Escolha o workflow adequado ao local onde a mensagem é criada.