astro-i18n

Also covers translating Content Collections per locale and adding hreflang alternate links via @astrojs/sitemap's i18n option for SEO. Does not cover general SEO meta tags beyond hreflang (astro-seo) or the Content Layer API itself (astro-content) — this skill focuses specifically on locale routing and URL generation.

Astro i18n

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

fuse-ai-pilot:explore-codebase - Analyze existing routing, content collections, and locale files
fuse-ai-pilot:research-expert - Verify latest Astro i18n docs via Context7/Exa
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	Setup and config options
Strategies	strategies.md	prefix-always vs prefix-other-locales
Helper functions	helper-functions.md	getRelativeLocaleUrl and all helpers
Content translation	content-translation.md	Translating content collections
Sitemap hreflang	sitemap-hreflang.md	SEO alternate links
Fallback	fallback.md	Missing translation fallback

Templates

Template	When to Use
i18n-config.md	Full i18n configuration
locale-page.md	Page component with locale awareness
language-switcher.md	Language switcher component

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