Guia de configuração de i18n no Astro: crie um site multilíngue em 30 minutos (com seletor de idioma)

Seu belo blog em Astro está pronto para alcançar o mercado internacional, mas você descobre que não sabe implementar suporte multilíngue. As opções locales, defaultLocale e prefixDefaultLocale parecem confusas, a organização do conteúdo em vários idiomas não está clara, você nem sabe direito o que são Content Collections e não faz ideia de como começar um seletor de idioma.

A configuração de i18n no Astro não é tão complicada; a documentação oficial apenas usa uma linguagem bastante técnica. Este artigo percorre todo o processo de configuração de i18n no Astro, da configuração básica ao seletor de idioma, com código completo em cada etapa. Em 30 minutos, seu site poderá oferecer vários idiomas.

Configuração básica de i18n no Astro (em 10 minutos)

Entendendo a configuração do astro.config.mjs

Vamos começar pelo mais importante: o arquivo de configuração. Desde a versão 4.0, o Astro oferece suporte integrado a i18n, e a configuração é bem simples. Abra seu astro.config.mjs e acrescente estas linhas:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    // Informa ao Astro quais idiomas o site oferece
    locales: ['en', 'zh-cn', 'ja'],

    // Idioma padrão (deve ser um dos itens de locales)
    defaultLocale: 'en',

    // Define se o idioma padrão recebe um prefixo no caminho
    prefixDefaultLocale: false,
  }
});

Vamos analisar cada opção:

locales — é a lista de todos os idiomas oferecidos pelo site. Use códigos de idioma padronizados, como 'en' (inglês), 'zh-cn' (chinês simplificado) e 'ja' (japonês). Se precisar distinguir variantes regionais, você também pode usar códigos como 'en-US' e 'en-GB'.

defaultLocale — é o idioma padrão, exibido quando alguém visita seu site pela primeira vez. O valor precisa estar presente no array locales; caso contrário, o Astro mostrará um erro.

prefixDefaultLocale — esta opção costuma gerar dúvidas. Quando definida como false, a URL do idioma padrão não inclui prefixo de idioma (por exemplo, /about), enquanto os demais idiomas incluem esse prefixo (como /zh-cn/about e /ja/about). Quando definida como true, todos os idiomas usam prefixo (/en/about, /zh-cn/about).

Na maioria dos casos, false é suficiente e deixa as URLs do idioma padrão mais curtas. Se a uniformidade das URLs for muito importante para você ou se houver requisitos específicos de SEO, considere usar true.

Comparação entre três estratégias de rotas

O roteamento i18n do Astro oferece três estratégias. A tabela abaixo ajuda a escolher a mais adequada:

Minha recomendação: se o projeto for simples, como um blog ou site de documentação, use diretamente a estratégia 1. Se preferir URLs uniformes, escolha a estratégia 2. A estratégia 3 é voltada a projetos com necessidades específicas, como selecionar o idioma de forma dinâmica conforme o comportamento do usuário ou servir idiomas diferentes em subdomínios distintos.

Neste ponto, você talvez esteja pensando: “Quero apenas um blog bilíngue em chinês e inglês; basta copiar a configuração acima e ajustá-la?” Sim, é exatamente isso. Altere locales para ['zh-cn', 'en'] e defina defaultLocale como 'zh-cn' (supondo que o público principal fale chinês). A configuração estará pronta.

Organização de conteúdo multilíngue (duas opções)

Com a configuração pronta, o próximo passo é organizar o conteúdo em vários idiomas. É aqui que muita gente trava: onde cada arquivo deve ficar? O Astro oferece dois caminhos, e você pode escolher o mais conveniente.

Opção 1: pastas por idioma (recomendada para iniciantes)

Esta é a abordagem mais intuitiva: uma pasta para cada idioma, assim:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

src/pages/
├── about.astro        # Idioma padrão (neste exemplo, chinês)
├── blog.astro
├── index.astro
├── en/                # Versão em inglês
│   ├── about.astro
│   ├── blog.astro
│   └── index.astro
└── ja/                # Versão em japonês
    ├── about.astro
    ├── blog.astro
    └── index.astro

Observe que, se você usar prefixDefaultLocale: false (idioma padrão sem prefixo), os arquivos do idioma padrão ficam diretamente na raiz de pages. Apenas os outros idiomas precisam de subpastas próprias.

A vantagem é uma estrutura clara, com páginas independentes para cada idioma, de modo que uma alteração não afeta as demais versões. A desvantagem é a grande quantidade de arquivos e código repetido quando o site cresce. Com 20 páginas e cinco idiomas, por exemplo, você precisaria manter 100 arquivos — só de pensar já dá trabalho.

Opção 2: rotas dinâmicas (recomendada para usuários avançados)

Se a opção 1 parecer trabalhosa demais, experimente rotas dinâmicas. Um único arquivo pode atender a todos os idiomas:

src/pages/
└── [lang]/
    └── [...slug].astro

Depois, em [...slug].astro, renderize o conteúdo dinamicamente conforme o parâmetro lang:

---

// src/pages/[lang]/[...slug].astro
export function getStaticPaths() {
  const locales = ['zh-cn', 'en', 'ja'];
  const slugs = ['about', 'blog', 'contact'];

  return locales.flatMap((lang) =>
    slugs.map((slug) => ({
      params: { lang, slug },
    }))
  );
}

const { lang, slug } = Astro.params;
// Carrega o conteúdo correspondente conforme lang e slug

---

Esta abordagem reaproveita melhor o código e reduz o custo de manutenção, mas exige que você entenda a lógica de rotas dinâmicas do Astro. Se estiver começando com Astro, use primeiro a opção 1 e considere a opção 2 depois de ganhar familiaridade.

Content Collections para vários idiomas (essencial em blogs)

Até aqui falamos de arquivos de página, mas, para blogs, Content Collections é o ponto principal. Esse é o método de gerenciamento de conteúdo recomendado pelo Astro e funciona especialmente bem em sites focados em conteúdo, como blogs e documentação.

A estrutura de diretórios fica assim:

src/content/
└── blog/
    ├── en/
    │   ├── post-1.md
    │   └── post-2.md
    ├── zh-cn/
    │   ├── post-1.md
    │   └── post-2.md
    └── ja/
        ├── post-1.md
        └── post-2.md

Depois, defina o schema em src/content/config.ts:

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blogCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    author: z.string(),
    date: z.date(),
    lang: z.enum(['en', 'zh-cn', 'ja']),  // Campo de idioma
  }),
});

export const collections = {
  blog: blogCollection,
};

Na página, busque os artigos do idioma correspondente:

---

// src/pages/blog/index.astro
import { getCollection } from 'astro:content';

const currentLang = Astro.currentLocale;  // Obtém o idioma atual
const posts = await getCollection('blog', ({ data }) => {
  return data.lang === currentLang;  // Retorna apenas os artigos do idioma atual
});

---

Assim, os artigos do idioma escolhido pelo usuário são exibidos automaticamente. O próprio site da documentação oficial do Astro usa esse método para gerenciar conteúdo multilíngue, portanto é uma solução confiável.

Gerenciamento de traduções da interface

Além dos arquivos de conteúdo, você precisa traduzir textos fixos da interface, como a navegação, botões e rótulos de formulário. Recomendo criar um dicionário de traduções:

// src/i18n/ui.ts
export const ui = {
  'en': {
    'nav.home': 'Home',
    'nav.about': 'About',
    'nav.blog': 'Blog',
    'btn.readMore': 'Read More',
  },
  'zh-cn': {
    'nav.home': '首页',
    'nav.about': '关于',
    'nav.blog': '博客',
    'btn.readMore': '阅读更多',
  },
  'ja': {
    'nav.home': 'ホーム',
    'nav.about': '概要',
    'nav.blog': 'ブログ',
    'btn.readMore': '続きを読む',
  },
} as const;

Em seguida, crie duas funções auxiliares:

// src/i18n/utils.ts
import { ui } from './ui';

// Obtém o idioma atual pela URL
export function getLangFromUrl(url: URL) {
  const [, lang] = url.pathname.split('/');
  if (lang in ui) return lang as keyof typeof ui;
  return 'zh-cn';  // Idioma padrão
}

// Retorna a função de tradução
export function useTranslations(lang: keyof typeof ui) {
  return function t(key: keyof typeof ui[typeof lang]) {
    return ui[lang][key] || ui['zh-cn'][key];
  }
}

Use essas funções em um componente:

---

// Um componente qualquer
import { getLangFromUrl, useTranslations } from '@/i18n/utils';

const lang = getLangFromUrl(Astro.url);
const t = useTranslations(lang);

---

<nav>
  <a href="/">{t('nav.home')}</a>
  <a href="/about">{t('nav.about')}</a>
  <a href="/blog">{t('nav.blog')}</a>
</nav>

Esta solução é simples e prática: todas as traduções ficam concentradas em um único arquivo, o que facilita as alterações. Se o volume de texto for muito grande, você também pode separá-lo em vários arquivos JSON, organizados por módulo.

Como implementar um seletor de idioma (com código completo)

Com a configuração e a organização do conteúdo prontas, chegamos à parte mais importante: o seletor de idioma. Para ser sincero, esta foi a etapa que mais me deu trabalho no começo; precisei analisar a implementação de vários sites até entendê-la. Depois que você compreende as funções auxiliares do Astro, porém, tudo fica bem simples.

Entendendo as funções auxiliares de i18n do Astro

O Astro oferece algumas funções muito úteis para lidar com URLs multilíngues. Vamos conhecer as principais:

getRelativeLocaleUrl(locale, path) — retorna o caminho relativo de um idioma.

import { getRelativeLocaleUrl } from 'astro:i18n';

// Obtém a URL da página About em inglês
const url = getRelativeLocaleUrl('en', 'about');
// Retorna: '/en/about' ou '/about' (dependendo da configuração)

getAbsoluteLocaleUrl(locale, path) — retorna a URL absoluta, incluindo o domínio.

import { getAbsoluteLocaleUrl } from 'astro:i18n';

const url = getAbsoluteLocaleUrl('en', 'about');
// Retorna: 'https://example.com/en/about'

Astro.currentLocale — obtém o idioma da página atual.

---

const currentLang = Astro.currentLocale;
// Retorna: 'zh-cn', 'en' etc.

---

Astro.preferredLocale — obtém o idioma preferido do navegador do usuário, desde que seja oferecido pelo site.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

---

const browserLang = Astro.preferredLocale;
// Retorna o idioma configurado no navegador, se ele estiver presente em locales

---

Com essas ferramentas, já podemos criar o seletor de idioma.

Criando o componente de seleção de idioma

Criei um seletor simples e prático que você pode copiar e usar diretamente:

---

// src/components/LanguageSwitcher.astro
import { getRelativeLocaleUrl } from 'astro:i18n';

// Todos os idiomas oferecidos (o ideal é ler do arquivo de configuração;
// aqui eles estão fixos apenas para facilitar o exemplo)
const locales = {
  'zh-cn': '简体中文',
  'en': 'English',
  'ja': '日本語',
};

// Obtém o idioma e o caminho atuais
const currentLang = Astro.currentLocale || 'zh-cn';
const currentPath = Astro.url.pathname
  .replace(`/${currentLang}/`, '/')  // Remove o prefixo do idioma
  .replace(/^\//, '');  // Remove a barra inicial

---

<div class="language-switcher">
  <button class="lang-button">
    {locales[currentLang]} ▼
  </button>
  <div class="lang-dropdown">
    {Object.entries(locales).map(([lang, label]) => {
      const url = getRelativeLocaleUrl(lang, currentPath);
      return (
        <a
          href={url}
          class={lang === currentLang ? 'active' : ''}
        >
          {label}
        </a>
      );
    })}
  </div>
</div>

<style>
  .language-switcher {
    position: relative;
    display: inline-block;
  }

  .lang-button {
    padding: 8px 16px;
    background: #f3f4f6;
    border: 1px solid #d1d5db;
    border-radius: 6px;
    cursor: pointer;
  }

  .lang-button:hover {
    background: #e5e7eb;
  }

  .lang-dropdown {
    display: none;
    position: absolute;
    top: 100%;
    right: 0;
    margin-top: 4px;
    background: white;
    border: 1px solid #d1d5db;
    border-radius: 6px;
    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
    min-width: 150px;
  }

  .language-switcher:hover .lang-dropdown {
    display: block;
  }

  .lang-dropdown a {
    display: block;
    padding: 10px 16px;
    color: #374151;
    text-decoration: none;
    transition: background 0.2s;
  }

  .lang-dropdown a:hover {
    background: #f3f4f6;
  }

  .lang-dropdown a.active {
    background: #dbeafe;
    color: #1e40af;
    font-weight: 500;
  }
</style>

<script>
  // Alterna o menu ao tocar em dispositivos móveis
  document.querySelector('.lang-button')?.addEventListener('click', (e) => {
    e.stopPropagation();
    const dropdown = document.querySelector('.lang-dropdown');
    dropdown?.classList.toggle('show');
  });

  // Fecha o menu ao clicar em qualquer outro lugar
  document.addEventListener('click', () => {
    document.querySelector('.lang-dropdown')?.classList.remove('show');
  });
</script>

Para usar o componente, importe-o no Layout ou na barra de navegação:

---

// src/layouts/Layout.astro
import LanguageSwitcher from '@/components/LanguageSwitcher.astro';

---

<header>
  <nav>
    <!-- Outros itens de navegação -->
    <LanguageSwitcher />
  </nav>
</header>

A lógica principal do componente é:

1. Obter o idioma e o caminho atuais
2. Gerar a URL correspondente para cada idioma oferecido
3. Destacar o idioma atual
4. Navegar para a página no idioma escolhido ao clicar

Talvez você tenha notado o uso de getRelativeLocaleUrl(lang, currentPath) para gerar a URL. Isso garante que, ao trocar de idioma, o usuário permaneça na mesma página em outra versão linguística, em vez de voltar à página inicial.

Detecção do idioma do navegador (opcional, mas recomendada)

Em alguns casos, você pode querer redirecionar automaticamente quem visita o site pela primeira vez para o idioma configurado no navegador. Isso pode ser feito com middleware:

// src/middleware.ts
import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware((context, next) => {
  const url = context.url;
  const currentLocale = context.currentLocale;
  const preferredLocale = context.preferredLocale;

  // Ao acessar a raiz, redireciona se o idioma do navegador for diferente do atual
  if (url.pathname === '/' && preferredLocale && preferredLocale !== currentLocale) {
    return context.redirect(`/${preferredLocale}/`);
  }

  return next();
});

Assim, na primeira visita, o usuário é direcionado automaticamente para um idioma familiar. Mas tome cuidado para não forçar esse redirecionamento em todas as visitas: caso contrário, depois de trocar o idioma manualmente, o usuário seria enviado de volta, o que resulta em uma experiência ruim.

Uma solução melhor é usar um cookie para lembrar a escolha do usuário:

// Versão aprimorada do middleware
export const onRequest = defineMiddleware((context, next) => {
  const url = context.url;
  const currentLocale = context.currentLocale;
  const preferredLocale = context.preferredLocale;
  const savedLang = context.cookies.get('user-lang')?.value;

  // Prioriza o idioma salvo pelo usuário
  if (savedLang && savedLang !== currentLocale && url.pathname === '/') {
    return context.redirect(`/${savedLang}/`);
  }

  // Caso contrário, usa o idioma do navegador
  if (!savedLang && url.pathname === '/' && preferredLocale && preferredLocale !== currentLocale) {
    context.cookies.set('user-lang', preferredLocale, {
      path: '/',
      maxAge: 31536000,  // 1 ano
    });
    return context.redirect(`/${preferredLocale}/`);
  }

  return next();
});

No seletor de idioma, atualize também o cookie quando o usuário fizer uma escolha:

<script>
  document.querySelectorAll('.lang-dropdown a').forEach((link) => {
    link.addEventListener('click', (e) => {
      const lang = e.target.getAttribute('data-lang');
      document.cookie = `user-lang=${lang}; path=/; max-age=31536000`;
    });
  });
</script>

Assim, o idioma escolhido fica salvo e será exibido diretamente na próxima visita.

Técnicas avançadas (fallback, mapeamento de domínio e SEO)

Com os recursos básicos prontos, vamos conhecer algumas técnicas avançadas. Se o projeto for simples, você pode pular esta parte por enquanto e voltar quando precisar.

Configuração da estratégia de fallback

Imagine que você esteja traduzindo o conteúdo gradualmente e algumas páginas em japonês ainda não estejam prontas. Quando alguém acessar uma página inexistente em japonês, você pode exibir a versão em inglês como alternativa. Essa é a estratégia de fallback:

// astro.config.mjs
export default defineConfig({
  i18n: {
    locales: ['en', 'zh-cn', 'ja'],
    defaultLocale: 'en',
    fallback: {
      ja: 'en',      // Se a versão japonesa não existir, exibe a inglesa
      'zh-cn': 'en', // Se a versão chinesa não existir, também exibe a inglesa
    },
  }
});

Com essa configuração, se /ja/some-page não existir, o Astro exibirá automaticamente o conteúdo de /en/some-page, em vez de uma página 404. Esse recurso é especialmente útil em sites cujo conteúdo ainda está sendo traduzido.

Mapeamento personalizado de domínios

Alguns produtos internacionais usam domínios diferentes para cada idioma, por exemplo:

• Inglês: example.com
• Chinês: example.cn
• Japonês: example.jp

O Astro também aceita essa configuração. Vale lembrar que o mapeamento de domínios só funciona no modo SSR (renderização no servidor):

// astro.config.mjs
export default defineConfig({
  output: 'server',  // É obrigatório habilitar SSR
  adapter: node(),   // É necessário configurar um adaptador
  i18n: {
    locales: ['en', 'zh-cn', 'ja'],
    defaultLocale: 'en',
    domains: {
      'zh-cn': 'https://example.cn',
      ja: 'https://example.jp',
    },
  }
});

Depois disso, o conteúdo em chinês será implantado automaticamente em example.cn, e o conteúdo em japonês, em example.jp. Esse recurso não está disponível se o projeto for um site estático, que é o modo padrão.

Pontos essenciais de SEO

A otimização de SEO para sites multilíngues consiste principalmente em informar aos mecanismos de busca quais versões linguísticas cada página oferece. A tag mais importante é hreflang.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

A boa notícia é que o suporte do Astro a SEO internacional é bastante amigável: com a configuração correta, muito trabalho acontece automaticamente. Ainda assim, alguns pontos exigem ação manual:

1. Adicione tags hreflang ao Layout

---

// src/layouts/Layout.astro
import { getAbsoluteLocaleUrl } from 'astro:i18n';

const locales = ['en', 'zh-cn', 'ja'];
const currentPath = Astro.url.pathname
  .replace(/^\/(en|zh-cn|ja)\//, '')
  .replace(/^\//, '');

---

<html>
<head>
  <!-- Adiciona uma tag hreflang para cada idioma -->
  {locales.map((lang) => (
    <link
      rel="alternate"
      hreflang={lang}
      href={getAbsoluteLocaleUrl(lang, currentPath)}
    />
  ))}

  <!-- Adiciona a tag do idioma padrão -->
  <link
    rel="alternate"
    hreflang="x-default"
    href={getAbsoluteLocaleUrl('en', currentPath)}
  />

  <!-- Descrição meta localizada -->
  <meta name="description" content={description[currentLang]} />

  <!-- URL canônica -->
  <link rel="canonical" href={getAbsoluteLocaleUrl(currentLang, currentPath)} />
</head>
</html>

2. Configuração multilíngue do sitemap.xml

Se você usa o plugin @astrojs/sitemap, ele gera automaticamente um sitemap para cada idioma. Basta garantir que o parâmetro site esteja definido:

// astro.config.mjs
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',  // Configuração obrigatória
  integrations: [sitemap()],
});

3. Localize os metadados

Não se esqueça de traduzir metadados como title, description e keywords para cada idioma:

---

const meta = {
  'en': {
    title: 'Welcome to My Blog',
    description: 'A blog about web development',
  },
  'zh-cn': {
    title: '欢迎来到我的博客',
    description: '一个关于 Web 开发的博客',
  },
};

const currentLang = Astro.currentLocale || 'en';

---

<head>
  <title>{meta[currentLang].title}</title>
  <meta name="description" content={meta[currentLang].description} />
</head>

Depois de concluir esses pontos, os mecanismos de busca poderão indexar corretamente seu site multilíngue.

Conclusão

Depois de tudo isso, vamos revisar o processo completo de configuração de i18n no Astro:

Etapa 1: configure o astro.config.mjs (5 minutos)

• Defina o array locales (idiomas oferecidos)
• Defina defaultLocale (idioma padrão)
• Escolha a estratégia de prefixDefaultLocale conforme suas necessidades

Etapa 2: organize o conteúdo multilíngue (escolha a opção mais adequada)

• Para iniciantes: pastas separadas por idioma
• Para usuários avançados: rotas dinâmicas + Content Collections
• Não se esqueça de configurar o dicionário de traduções da interface

Etapa 3: implemente o seletor de idioma (basta copiar e adaptar o código)

• Use getRelativeLocaleUrl para gerar URLs
• Use Astro.currentLocale para obter o idioma atual
• Opcional: adicione detecção do idioma do navegador e memorização com cookies

Depois de usar i18n no Astro por algum tempo, percebi como ele é prático. A configuração é simples, as funções auxiliares são úteis e o desempenho é muito bom, pois as rotas de todos os idiomas são pré-geradas durante o build. Se o seu site precisa oferecer vários idiomas, a solução integrada do Astro certamente merece uma tentativa.

Comece agora mesmo a adicionar suporte multilíngue ao seu site Astro. Se encontrar algum problema, consulte a documentação oficial de i18n do Astro, que traz informações mais detalhadas sobre a API.

Se você tiver experiências práticas ou armadilhas que encontrou pelo caminho, compartilhe nos comentários para que possamos aprender juntos.