fusengine/agents/astro-i18n

<objective> Implements Astro's built-in i18n system (Astro 3.5+): file-based locale routing under src/pages/[locale]/, defaultLocale and routing-strategy configuration (prefix-always vs prefix-other-locales), URL helper functions from astro:i18n (getRelativeLocaleUrl, getAbsoluteLocaleUrl), reading Astro.currentLocale in components, and fallback-locale configuration to avoid 404s on missing translations.

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. </objective>

Astro i18n

Agent Workflow (MANDATORY)

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

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

Templates

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