Astro Starlight i18n and Multilingual Sites Tutorial

What You Are Learning

This tutorial introduces internationalization, often shortened to i18n. In a Starlight site, i18n means supporting multiple languages or locale versions of your documentation.

• What i18n means.
• When multilingual docs are worth it.
• How language folders are usually organized.
• How to plan translated navigation.
• How worldbuilding sites can use language sections creatively.

The Big Picture

Default language pages
  ↓
Translated language folders
  ↓
Locale-aware navigation
  ↓
Readers choose their language

When to Use i18n

Use i18n when:
- You have real readers in multiple languages
- The content will be maintained long-term
- Translations will be kept updated
- Navigation and metadata can also be translated

When Not to Use i18n Yet

Avoid i18n at first when:
- The site is still changing constantly
- You only have one or two test translations
- You cannot maintain translated pages
- You are still learning Starlight basics

Basic Language Folder Concept

src/content/docs/
  index.md
  getting-started.md
  es/
    index.md
    getting-started.md
  fr/
    index.md
    getting-started.md

The exact setup depends on your configuration, but the concept is the same: each language needs translated content and navigation.

Locale Planning

Examples:
en     English
en-US  English, United States
es     Spanish
fr     French
ja     Japanese

Use simple language codes unless you need regional differences.

Translated Metadata

---
title: "Introducción"
description: "Aprende cómo usar este sitio de documentación."
---

Do not translate only the body while leaving all page metadata in the original language.

Translated Navigation

English:
Start Here
Lessons
Reference

Spanish:
Comienza Aquí
Lecciones
Referencia

Fallback Content

Fallback content means showing a default-language page when a translation is missing. This can be useful, but it can also confuse readers if not clearly signposted.

Good practice:
- Translate core navigation first
- Translate starting pages first
- Clearly indicate when content is not yet translated

Right-to-Left Languages

Some languages read right-to-left. If your site supports languages such as Arabic or Hebrew, check layout, sidebar behavior, code blocks, tables, and diagrams carefully.

Worldbuilding Uses

A world bible can use i18n in two ways:

• Real multilingual support: the site is available in real-world languages.
• Creative in-world language sections: documents appear as translated archives from different cultures or factions.

Lesson Site Uses

1. Homepage.
2. Getting started page.
3. Navigation labels.
4. Beginner lessons.
5. Reference pages.

i18n Maintenance Checklist

[ ] Which languages are supported?
[ ] Who maintains translations?
[ ] Are titles translated?
[ ] Are descriptions translated?
[ ] Is the sidebar translated?
[ ] Are images and diagrams still understandable?
[ ] Are code examples language-neutral where possible?
[ ] Is missing translation behavior clear?

Simple Rule of Thumb

Do not add languages casually.
Translate the reader path first.
Keep navigation understandable.
Keep translations updated.
A half-maintained multilingual site can be worse than a clear single-language site.