Traduzir páginas no Astro

Você traduz uma página Astro envolvendo seu texto em t() e seus links internos em href(), ambos lidos de Astro.locals. Tudo roda no servidor, e um arquivo de página atende a todos os idiomas.

Antes de começar

• A integração está instalada e <UniversallyHead /> está no seu layout. Veja Instalar a integração Astro.
• O projeto tem pelo menos um idioma de destino com o switch Ativado.

Traduza texto com t()

1. Leia t de Astro.locals no frontmatter da página.
2. Passe cada pedaço de texto de origem para ele.

---
const { t } = Astro.locals;
---

<h1>{t('About us')}</h1>
<p>{t('We translate websites.')}</p>

t() recebe seu texto de origem e retorna o texto para o idioma que está sendo renderizado. O texto de origem é a chave, então a string no seu código tem que corresponder à string de origem no painel, caractere por caractere. Um espaço extra ou uma vírgula alterada a torna uma string diferente.

Uma string sem tradução ainda retorna o texto de origem, então uma página nunca quebra enquanto uma tradução está a caminho. A string é registrada uma vez e reportada após a resposta. Em páginas de idioma de origem, t() retorna seu argumento sem consulta e sem relatório.

Nunca chame t(''). O tradutor recusa uma string vazia, e esse relatório falha com um erro registrado.

Localize links com href()

1. Leia href de Astro.locals.
2. Envolva cada caminho interno.

---
const { t, href } = Astro.locals;
---

<a href={href('/pricing')}>{t('See pricing')}</a>

Em uma página em francês, /pricing se torna /fr/pricing, e a string de consulta e o hash são mantidos. No idioma de origem, o caminho volta inalterado, pois o idioma de origem é servido sem um prefixo.

href() também retorna estes inalterados:

• uma string vazia
• URLs relativas de protocolo que começam com //
• qualquer coisa que não comece com /: links https: e mailto:, links tel:, #fragmento, ?query e caminhos relativos
• um caminho que já carrega o prefixo, como /fr ou /fr/pricing, então chamá-lo duas vezes não causa danos

Leia o idioma atual

Astro.locals.lang contém o código da variante do idioma que está sendo renderizado, em minúsculas: fr para francês (França), es-419 para espanhol (México) e en-us em uma página de origem em inglês (EUA). Astro.locals contém lang, t e href, e nada mais.

Mantenha o HTML inline dentro de t()

Tags <strong> e <em> simples podem ficar dentro da string. Renderize o resultado com set:html:

---
const { t } = Astro.locals;
---

<p set:html={t('Wrap text in <strong>t()</strong> and keep your <em>markup</em> intact.')} />

Uma string que contém uma tag é normalizada antes da tradução: atributos em tags inline são substituídos por marcadores, e elementos img e svg são esvaziados. Mantenha as strings como texto simples, ou como <strong> e <em> sem atributos.

Mantenha <a> fora de t():

---
const { t, href } = Astro.locals;
---

<p>{t('Compare every plan.')} <a href={href('/pricing')}>{t('See pricing')}</a></p>

A URL do link pertence a um idioma, então href() tem que criá-la. Uma URL dentro do texto fonte também torna a chave diferente em cada página que linka para outro lugar, o que divide uma tradução em muitas.

Passe texto traduzido para ilhas

Não existe t() no lado do cliente. Um componente que hidrata no navegador recebe texto traduzido apenas como props do arquivo .astro:

---
import Counter from '../components/Counter.tsx';

const { t } = Astro.locals;
---

<Counter client:load label={t('Add one')} />

Traduza um site estático

Com output: 'static', a tradução acontece durante o build:

1. Execute o build. Ele carrega cada idioma, renderiza cada página uma vez, então envia todas as strings que não tinha em uma única chamada.
2. Leia o final do log. Se algo era novo, ele imprime uma linha como 12 novas strings traduzidas. Reconstrua para incluí-las.
3. Execute o build novamente. As novas strings agora estão no HTML.

Um site estático não tem código de servidor rodando após o build. Edições no painel chegam a ele apenas quando você reconstrói e reimplantar, como descrito em Atualizações de tradução no Astro.

Verificar se funcionou

Abra uma página sob um prefixo de destino, como /fr/about. O texto que você envolveu em t() aparece traduzido após uma recarga, e links criados com href() apontam para caminhos /fr/. O texto que você não envolveu permanece no seu idioma fonte: nada na página é traduzido a menos que passe por t().

Se não funcionar

• Uma string permanece no idioma fonte enquanto o resto traduz: sua chave não corresponde ao painel. Compare o argumento de t() com a string fonte, caractere por caractere.
• Todas as strings permanecem no idioma fonte: verifique o log do servidor para word limit reached. Veja Solução de problemas de integração do Astro.