AgentSkillsCN

astro-i18n

当在 Astro 中实施国际化、配置 i18n 路由、设置区域策略、使用 getRelativeLocaleUrl/getAbsoluteLocaleUrl、处理 Astro.currentLocale 或添加带有站点地图的 hreflang 标签时使用。

SKILL.md
--- frontmatter
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.
versions:
  astro: "6"
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-6, astro-content, astro-seo, solid-astro

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

TopicReferenceWhen to Consult
Routing configrouting-config.mdSetup and config options
Strategiesstrategies.mdprefix-always vs prefix-other-locales
Helper functionshelper-functions.mdgetRelativeLocaleUrl and all helpers
Content translationcontent-translation.mdTranslating content collections
Sitemap hreflangsitemap-hreflang.mdSEO alternate links
Fallbackfallback.mdMissing translation fallback

Templates

TemplateWhen to Use
i18n-config.mdFull i18n configuration
locale-page.mdPage component with locale awareness
language-switcher.mdLanguage 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