# Astro I18N

> Use when implementing i18n in Astro — locale routing strategies, getRelativeLocaleUrl/getAbsoluteLocaleUrl, Astro.currentLocale, or hreflang with sitemap.

- Skill: `fusengine/astro-i18n` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add fusengine/astro-i18n`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fusengine/astro-i18n/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: fusengine (https://skillmd.com/u/fusengine)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/fusengine/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

| 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