git:20260729.3b91eed to git:20260904.5f1d30f

---

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)

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