🔧 Criando rotas dinâmicas para internacionalização (i18n) com Astro Build

If you want read this article in English go here

Recentemente, comecei a aprender Astro para criar um projeto no estilo de dashboard.

Eu realmente quero implementar a internacionalização (i18n) neste projeto—o objetivo é que qualquer pessoa possa usá-lo, independentemente do idioma.

Problema

O suporte a i18n no Astro é muito bom. Ele funciona de maneira semelhante ao Next.js ou qualquer outro framework com roteamento baseado na estrutura de arquivos/pastas.

Então, se quisermos ter uma página em inglês e a mesma página em português, podemos organizar nossos arquivos assim:

.
└── src/
    └── pages/
        ├── en/
        │   ├── login.astro
        │   └── dashboard.astro
        └── pt-br/
            ├── login.astro
            └── dashboard.astro

E cada página tem suas próprias strings i18n—legal!

Mas é aqui que meu problema começa: eu não quero clonar todas as minhas páginas; eu só quero mudar as strings nessas páginas.

Eu preciso de algo como /[qualquer-bandeira-de-idioma]/todas-as-minhas-rotas.

Você pode perguntar: "Por que não usar algo como react-intl?" Minha resposta é que eu quero aproveitar ao máximo o mecanismo do Astro, especialmente para SSG/SSR, e evitar quaisquer componentes do lado do cliente. Geralmente, esses frameworks usam React Context, que é renderizado apenas no lado do cliente.

Tentativas e Fracassos

Primeiro de tudo, eu li a receita do Astro sobre i18n e conferi algumas bibliotecas da comunidade para resolver esse problema.

A primeira biblioteca que testei foi a astro-i18next, e parecia exatamente o que eu precisava!

Com base em um array no arquivo de configuração, o astro-i18next gera minhas páginas i18n no momento da build, então eu só preciso codificar uma vez e não me preocupar em clonar páginas.

O problema é que o astro-i18next parece estar arquivado ou não ser mais mantido. Há muitos problemas e o último commit foi há mais de um ano.

Solução

Depois de tentar outras bibliotecas (menção honrosa para astro-i18n), encontrei o Paraglide, e ele foi um divisor de águas para o meu projeto.

Escolhi o Paraglide porque:

• Ele é seguro por tipo, então eu posso usá-lo com TypeScript e aproveitar o autocomplete.
• Ele converte strings i18n em funções, então se uma chave de string mudar, minha build falhará, capturando erros cedo.
• Usar funções i18n permite uma melhor tree shaking, removendo funções não utilizadas.
• Existe uma extensão do VS Code que melhora a experiência de desenvolvimento.

Nota: Você pode usar o Paraglide em um projeto JS também, e ele também suporta Next.js.

Após a instalação e configuração, usei minhas mensagens assim:

---
import * as m from "../paraglide/messages.js";
---

<h1>{m.hello({ name: "Alan" })}</h1>

No entanto, isso não resolveu meu problema de roteamento—eu ainda estava clonando minhas páginas para cada idioma que queria adicionar.

Para resolver isso, mudei meu projeto para usar rotas dinâmicas na rota raiz, então todas as minhas rotas agora começam com a bandeira do idioma.

Minha estrutura de pastas ficou assim:

.
└── src/
    └── pages/
        └── [lang]/
            ├── login.astro
            └── dashboard.astro

Depois dessa mudança, o Paraglide pode obter automaticamente o idioma do parâmetro da rota:

• http://localhost:4321/en/login
• http://localhost:4321/pt-br/login

Agora, posso adicionar um novo idioma apenas configurando-o em astro.config.ts e traduzindo meu arquivo de strings.

Mas ainda tenho dois problemas para resolver:

1. Quando o usuário acessa http://localhost:4321/ pela primeira vez sem uma bandeira de idioma.
2. Se o usuário mudar o idioma em uma rota específica, preciso mantê-lo na mesma rota (por exemplo, /en/create-account deve redirecionar para /pt-br/create-account ou /pt-br/criar-conta).

Middleware para Redirecionamento de Idioma

Para resolver o primeiro problema de redirecionamento de idioma, usei middlewares do Astro.

Em src/middleware/index.ts, adicionei este código:

import { defineMiddleware } from 'astro:middleware';
import {
  languageTag,
  setLanguageTag,
  type AvailableLanguageTag,
} from '../paraglide/runtime';

export const onRequest = defineMiddleware((context, next) => {
  // Obter o idioma do parâmetro da URL
  const lang = context.params.lang;

  // Se mudou
  if (lang !== languageTag()) {
    setLanguageTag(lang as AvailableLanguageTag);
    // Redirecionar para o idioma alterado ou padrão (en)
    return context.redirect(`/${lang ?? 'en'}`);
  }

  return next();
});

Seletor de Idioma com Rota Atual

Para manter o usuário na mesma rota ao mudar de idioma, adicionei este componente:

---
import { languageTag } from '../paraglide/runtime';

const pathName = Astro.url.pathname.replace(`/${languageTag()}/`, '');
---

<ul>
  <li>
    <a href={`/pt-br/${pathName}`}>Ir para Português</a>
  </li>
  <li>
    <a href={`/en/${pathName}`}>Go to English</a>
  </li>
</ul>

Além disso, podemos traduzir essas mensagens também, usando o segundo parâmetro na função de mensagens do Paraglide:

<ul>
  <li>
    <a href={`/pt-br/${pathName}`}>{m.goToLanguage(undefined, { languageTag: 'pt-br' })}</a>
  </li>
  <li>
    <a href={`/en/${pathName}`}>{m.goToLanguage(undefined, { languageTag: 'en' })}</a>
  </li>
</ul>

Considerações

Não considero minha solução a melhor, especialmente porque ainda estou aprendendo Astro, então pode haver outras soluções. Se você souber de alguma, por favor comente, e eu tentarei :)

Obrigado por ler este artigo! Se você tiver alguma dúvida, comente, ficarei feliz em responder.