/astro-i18n

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