Um Guia Rápido para Localizar um Site Astro

Construindo um site multilíngue com Astro? Você precisa lidar com dois desafios distintos: organizar suas páginas de conteúdo por idioma e traduzir elementos da interface como botões e navegação. Este guia mostra exatamente como configurar localização estática e dinâmica no Astro, desde a configuração básica até recursos prontos para produção.

Configurando o Roteamento i18n do Astro para Conteúdo Estático

Configurando astro.config.mjs para Suporte Multilíngue

Comece configurando o roteamento i18n integrado do Astro no seu arquivo astro.config.mjs. Isso informa ao Astro quais idiomas você suporta e como estruturar suas URLs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    routing: {
      prefixDefaultLocale: true // Use /en/ para URLs em inglês
    }
  }
});

Definir prefixDefaultLocale: true garante que todos os idiomas usem padrões de URL consistentes (/en/about, /es/about), facilitando o gerenciamento de links e evitando conflitos de roteamento posteriormente.

Criando Estrutura de Pastas Localizadas

Organize suas páginas criando pastas específicas para cada locale em src/pages/:

src/pages/
  en/
    index.astro
    about.astro
  es/
    index.astro
    about.astro
  fr/
    index.astro
    about.astro

Cada pasta corresponde a um locale definido na sua configuração. O Astro gera automaticamente as rotas corretas baseadas nesta estrutura.

Gerenciando Localização Estática e Dinâmica no Astro

Organizando Coleções de Conteúdo por Locale

Para posts de blog, documentação ou qualquer coleção de conteúdo, espelhe a mesma estrutura de locale:

src/content/
  blog/
    en/
      first-post.md
    es/
      first-post.md
    fr/
      first-post.md

Ao consultar conteúdo, filtre pelo locale atual:

import { getCollection } from 'astro:content';

const posts = await getCollection('blog', ({ id }) => {
  return id.startsWith(Astro.currentLocale + '/');
});

Implementando Rotas Dinâmicas com Pastas [locale]

Em vez de duplicar arquivos de página para cada idioma, use rotas dinâmicas. Crie uma pasta [locale]:

src/pages/
  [locale]/
    index.astro
    about.astro
    blog/
      [slug].astro

Nas suas páginas, use getStaticPaths() para gerar rotas para todos os locales:

export function getStaticPaths() {
  return [
    { params: { locale: 'en' } },
    { params: { locale: 'es' } },
    { params: { locale: 'fr' } }
  ];
}

Lidando com Strings Dinâmicas da Interface com Paraglide

Instalando e Configurando o Paraglide para Astro

Enquanto o Astro lida com o roteamento de páginas, você precisa de uma solução para texto da interface. O Paraglide oferece excelente suporte ao TypeScript e tamanho mínimo de bundle:

npm install @inlang/paraglide-js @inlang/paraglide-astro
npx @inlang/paraglide-js init

Criando Arquivos de Tradução e Chaves de Mensagem

Armazene suas traduções em messages/ na raiz do seu projeto:

// messages/en.json
{
  "nav.home": "Home",
  "nav.about": "About",
  "button.readMore": "Read more"
}

// messages/es.json
{
  "nav.home": "Inicio",
  "nav.about": "Acerca de",
  "button.readMore": "Leer más"
}

Importe e use traduções nos seus componentes:

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

<nav>
  <a href={`/${Astro.currentLocale}`}>{m.nav_home()}</a>
  <a href={`/${Astro.currentLocale}/about`}>{m.nav_about()}</a>
</nav>

Construindo um Seletor de Idioma e Navegação

Usando getRelativeLocaleUrl() para URLs Limpas

O Astro fornece funções auxiliares para gerar URLs localizadas adequadas. Sempre use getRelativeLocaleUrl() em vez de concatenação manual de strings:

import { getRelativeLocaleUrl } from 'astro:i18n';

const aboutUrl = getRelativeLocaleUrl(Astro.currentLocale, 'about');
const blogUrl = getRelativeLocaleUrl(Astro.currentLocale, 'blog/my-post');

Crie um componente seletor de idioma:

---
import { getRelativeLocaleUrlList } from 'astro:i18n';

const localeUrls = getRelativeLocaleUrlList();
---

<select onchange="window.location.href = this.value">
  {localeUrls.map(url => {
    const locale = url.split('/')[1];
    return (
      <option value={url} selected={Astro.currentLocale === locale}>
        {locale.toUpperCase()}
      </option>
    );
  })}
</select>

Evitando Armadilhas Comuns Como Rotas com Prefixo Duplo

Fique atento a estes erros comuns:

1. Prefixos duplos: Ao usar rotas dinâmicas, limpe seus slugs para evitar URLs como /en/blog/en/my-post:

const cleanSlug = post.slug.replace(`${locale}/`, '');

2. Caminhos de locale codificados: Sempre use os auxiliares i18n do Astro em vez de concatenação de strings
3. Locale ausente nos links: Todo link interno precisa de localização adequada

Recursos Avançados de i18n do Astro

Configurando Idiomas de Fallback

Configure fallbacks para conteúdo não traduzido:

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    fallback: {
      es: 'en',
      fr: 'en'
    },
    routing: {
      fallbackType: 'rewrite' // Mostra conteúdo de fallback sem redirecionar
    }
  }
});

Configurando Mapeamento de Domínio para Produção

Para sites de produção com domínios separados por idioma:

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    domains: {
      fr: 'https://fr.example.com',
      es: 'https://example.es'
    }
  }
});

Isso requer renderização do lado do servidor com o adaptador @astrojs/node ou @astrojs/vercel.

Conclusão

Localizar um site Astro combina duas abordagens: roteamento i18n integrado para organização de conteúdo estático e bibliotecas externas como o Paraglide para strings dinâmicas da interface. Comece com a estrutura de pastas e configuração de roteamento, depois adicione o gerenciamento de traduções. Lembre-se de usar os auxiliares de URL do Astro para evitar problemas comuns de roteamento, e considere fallbacks e mapeamento de domínio para implantações em produção.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.