Internacionalização (i18n)

Esta página documenta como o site de documentação do Apothem lida com vários idiomas: a coorte de localidades que ele declara, o mecanismo hreflang que ele emite, sua renderização da direita para a esquerda e como as páginas de cada idioma são conectadas ao roteamento.

Resumo das decisõesCopy Anchor Link

• Plataforma: Next.js App Router + Fumadocs. O site é compilado a partir de site/. A coorte de localidades é declarada em site/lib/i18n.ts, e o mecanismo de links de idioma alternativo fica em site/lib/hreflang.ts.
• Coorte de localidades: doze idiomas. A coorte Modern Dev de doze localidades é a fonte da verdade canônica, com o inglês como localidade de origem e cada um dos onze alvos semeado por máquina a partir do conjunto de páginas em inglês; a revisão humana por localidade está em andamento, e fallbackLanguage: 'en' cobre qualquer página que uma localidade ainda não tenha redigido.
• Roteamento por localidade: habilitado em toda a coorte. Cada localidade está conectada ao roteamento e acessível em seu próprio prefixo de URL (/es/, /zh-cn/, …); o inglês é servido na raiz do site.
• Mecanismo hreflang: ativo. Cada página emite um conjunto de <link rel="alternate"> que cobre cada localidade mais um fallback x-default, de modo que os mecanismos de busca vejam o cluster completo de idiomas alternativos. Os links são resolvidos arquivo a arquivo a partir do sistema de arquivos, então uma página é anunciada em uma localidade somente quando essa localidade a tem.
• Renderização da direita para a esquerda: ativa. As folhas de estilo compartilhadas usam propriedades CSS lógicas em todo lugar, então as páginas em árabe são renderizadas corretamente sob dir="rtl".
• Revisão da tradução: rastreada por página. As páginas de localidade semeadas por máquina são servidas e carregam machineTranslated: true em seu frontmatter até que uma pessoa as revise; a marcação é um metadado de acompanhamento da revisão e a página não a exibe. O inglês é o fallback para qualquer página que falte a uma localidade. Ter 80% das páginas de uma localidade revisadas é uma meta de revisão, não um bloqueio à publicação.
• Atualidade da tradução: rastreada por página. Cada página de localidade registra o texto em inglês a partir do qual foi traduzida. Quando a página em inglês muda depois, a página traduzida mostra uma nota de uma linha com um link para a página em inglês, que permanece autoritativa.

A coorte de localidadesCopy Anchor Link

A coorte Modern Dev declara doze localidades. O inglês é servido na raiz do site; cada um dos onze alvos é semeado por máquina a partir do conjunto de páginas em inglês, em seu próprio prefixo de URL, com fallbackLanguage: 'en' cobrindo qualquer página ainda não redigida.

A coorte é a única fonte da verdade; alterações nela passam por uma decisão deliberada, nunca por uma edição silenciosa.

Como o hreflang funcionaCopy Anchor Link

site/lib/hreflang.ts constrói o mapa alternates.languages que o Next.js renderiza no <head> de cada página. Sua construção respeita uma regra: o link de idioma alternativo de uma localidade é emitido somente quando essa localidade redigiu essa página, o que é resolvido arquivo a arquivo a partir do sistema de arquivos (site/lib/translated-pages.ts). Uma página totalmente traduzida, portanto, emite o cluster completo:

<link rel="alternate" hreflang="en" href="https://apothem.ahmedgad.com/..." />
<link rel="alternate" hreflang="es" href="https://apothem.ahmedgad.com/es/..." />
<link rel="alternate" hreflang="ar" href="https://apothem.ahmedgad.com/ar/..." dir="rtl" />
<!-- … one per cohort locale … -->
<link rel="alternate" hreflang="x-default" href="https://apothem.ahmedgad.com/..." />

O link canonical da página é sempre sua própria URL — ele nunca aponta para outra localidade.

Renderização da direita para a esquerdaCopy Anchor Link

O árabe é a localidade da direita para a esquerda da coorte, e o site o renderiza corretamente:

• Somente propriedades CSS lógicas. As folhas de estilo e os componentes compartilhados usam propriedades lógicas (margin-inline-start, padding-inline-end, text-align: start, inset-inline-start) em vez de físicas (margin-left, text-align: left). As propriedades lógicas se invertem automaticamente sob dir="rtl", então a mesma folha de estilo atende corretamente às duas direções.
• Atributo de direção. As páginas em árabe definem dir="rtl" no elemento <html> junto com lang="ar".
• Conteúdo bidirecional. Strings de direção mista — por exemplo, um comando em inglês dentro de um parágrafo em árabe — são envolvidas em <bdi> para que o trecho incorporado da esquerda para a direita seja renderizado corretamente dentro do fluxo da direita para a esquerda.

Adicionar ou atualizar uma localidadeCopy Anchor Link

A coorte e o roteamento são conduzidos por site/lib/i18n.ts:

1. Redija a página em content/docs/<locale>/ espelhando a fonte em inglês.
2. Registre o texto em inglês que ela traduz: a partir de site/, execute node scripts/translation-sources.mjs --stamp <locale>/<path>.mdx, que grava o hash da página em inglês no frontmatter sourceHash da página da localidade.
3. Confirme que a localidade está listada em ROUTED_LOCALES (todas as doze localidades da coorte são roteadas hoje).
4. Seu link hreflang e suas rotas são resolvidos automaticamente a partir do sistema de arquivos.

Traduções desatualizadasCopy Anchor Link

O sourceHash de uma página de localidade é o hash da página em inglês a partir da qual ela foi traduzida, cobrindo o frontmatter e a prosa em inglês, mas não as tabelas geradas que o gerador de referência reescreve em todos os idiomas de uma vez. No momento do build, o site calcula o hash da página em inglês atual; quando os dois diferem, a página traduzida mostra uma nota de que a página em inglês mudou desde que a tradução foi feita, com um link para ela. Execute node scripts/translation-sources.mjs a partir de site/ para listar as páginas desatualizadas por localidade e, em seguida, atualize cada tradução e aplique o carimbo como no passo 2 acima. Uma página que uma localidade não traduziu de forma alguma é servida a partir da fonte em inglês, marcada como texto em inglês.

O inglês continua sendo a fonte da verdade; cada página de localidade espelha literalmente a estrutura, os links e os exemplos de código de sua contraparte em inglês.