---
name: astro-i18n
description: Use when implementing i18n in Astro — locale routing strategies, getRelativeLocaleUrl/getAbsoluteLocaleUrl, Astro.currentLocale, or hreflang with sitemap.
versions:
  astro: "7"
user-invocable: true
references: references/routing-config.md, references/strategies.md, references/helper-functions.md, references/content-translation.md, references/sitemap-hreflang.md, references/fallback.md, references/templates/i18n-config.md, references/templates/locale-page.md, references/templates/language-switcher.md
related-skills: astro-7, astro-content, astro-seo, solid-astro
---

<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, 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