| name | astro-i18n |
| description | Use when implementing internationalization in Astro, configuring i18n routing, setting up locale strategies, using getRelativeLocaleUrl/getAbsoluteLocaleUrl, handling Astro.currentLocale, or adding hreflang tags with sitemap. |
Astro i18n
Targets: Astro 7.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 parallel agents (Codex spawn_agent):
- explore-codebase - Analyze existing routing, content collections, and locale files
- research-expert - Verify latest Astro i18n docs via Context7/Exa
- Context7 (official docs) - Check
astro:i18n API and sitemap integration
After implementation, run 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
Templates
Best Practices
- Use
getRelativeLocaleUrl() — never hardcode locale prefixes in links
Astro.currentLocale — read locale in components, not from URL manually- Content Collections per locale — organize translated content in
src/content/[type]/[locale]/
- Sitemap hreflang — always configure
@astrojs/sitemap with i18n option for SEO
- 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
