Agent-Skills.md

Agent Skills: Astro i18n

Use when implementing internationalization in Astro, configuring i18n routing, setting up locale strategies, using getRelativeLocaleUrl/getAbsoluteLocaleUrl, handling Astro.currentLocale, or adding hreflang tags with sitemap.

UncategorizedID: fusengine/agents/astro-i18n

Repository

fusengine/agents
fusengineLicense: MIT
7

Install this agent skill to your local

pnpm dlx add-skill https://github.com/fusengine/agents/tree/HEAD/plugins/astro-expert/skills/astro-i18n

Skill Files

Browse the full folder contents for astro-i18n.

Download Skill

Loading file tree…

plugins/astro-expert/skills/astro-i18n/SKILL.md

Skill Metadata

Name
astro-i18n
Description
Use when implementing internationalization in Astro, configuring i18n routing, setting up locale strategies, using getRelativeLocaleUrl/getAbsoluteLocaleUrl, handling Astro.currentLocale, or adding hreflang tags with sitemap.

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 | Setup and config options | | Strategies | strategies.md | prefix-always vs prefix-other-locales | | Helper functions | helper-functions.md | getRelativeLocaleUrl and all helpers | | Content translation | content-translation.md | Translating content collections | | Sitemap hreflang | sitemap-hreflang.md | SEO alternate links | | Fallback | fallback.md | Missing translation fallback |

Templates

| Template | When to Use | |----------|-------------| | i18n-config.md | Full i18n configuration | | locale-page.md | Page component with locale awareness | | 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