astro-i18n

Astro i18n

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase - Analyze existing routing, content collections, and locale files
2. fuse-ai-pilot:research-expert - Verify latest Astro i18n docs via Context7/Exa
3. mcp__context7__query-docs - Check astro:i18n API and sitemap integration

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

When to Use

• Building multilingual Astro sites with locale-prefixed URLs
• Configuring defaultLocale and routing strategies
• Generating locale-aware links with getRelativeLocaleUrl()
• Reading Astro.currentLocale in components and pages
• Adding hreflang alternate links via @astrojs/sitemap
• Translating content using Content Collections per locale

Built-in i18n (Astro 3.5+)

Astro's built-in i18n system provides:

• File-based locale routing via src/pages/[locale]/
• Routing strategies for URL prefix behavior
• URL helper functions from astro:i18n
• Middleware-based routing logic
• Fallback locale configuration

Reference Guide

Concepts

| Topic | Reference | When to Consult | |-------|-----------|-----------------| | Routing config | [routing-config.md](references/routing-config.md) | Setup and config options | | Strategies | [strategies.md](references/strategies.md) | prefix-always vs prefix-other-locales | | Helper functions | [helper-functions.md](references/helper-functions.md) | getRelativeLocaleUrl and all helpers | | Content translation | [content-translation.md](references/content-translation.md) | Translating content collections | | Sitemap hreflang | [sitemap-hreflang.md](references/sitemap-hreflang.md) | SEO alternate links | | Fallback | [fallback.md](references/fallback.md) | Missing translation fallback |

Templates

| Template | When to Use | |----------|-------------| | [i18n-config.md](references/templates/i18n-config.md) | Full i18n configuration | | [locale-page.md](references/templates/locale-page.md) | Page component with locale awareness | | [language-switcher.md](references/templates/language-switcher.md) | Language switcher component |

Best Practices

1. Use getRelativeLocaleUrl() — never hardcode locale prefixes in links
2. Astro.currentLocale — read locale in components, not from URL manually
3. Content Collections per locale — organize translated content in src/content/[type]/[locale]/
4. Sitemap hreflang — always configure @astrojs/sitemap with i18n option for SEO
5. Fallback locales — configure fallback to prevent 404s for missing translations

Forbidden

• Hardcoding locale strings in URL paths
• Parsing the URL manually to detect locale (use Astro.currentLocale)
• Skipping hreflang configuration for SEO-sensitive sites
• Using getRelativeLocaleUrl without configuring site in Astro config