<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->

# Internationalisation (i18n)

SSG provides built-in support for multi-locale static sites with hreflang injection, per-locale sitemaps, and a language switcher.

## Configuration

Add an `[i18n]` section to `ssg.toml`:

```toml
[i18n]
default_locale = "en"
locales = ["en", "fr", "de"]
url_prefix = "sub_path"
```

### Fields

| Field | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `default_locale` | String | `"en"` | Fallback locale, used for `x-default` |
| `locales` | List | `["en"]` | All supported locales |
| `url_prefix` | String | `"sub_path"` | URL strategy: `sub_path` or `sub_domain` |

### URL Prefix Strategies

- **`sub_path`** — locale as path prefix: `https://example.com/fr/about`
- **`sub_domain`** — locale as subdomain: `https://fr.example.com/about`

## Content Structure

Organize content in locale-prefixed directories:

```
content/
  en/
    index.md
    about.md
  fr/
    index.md
    about.md
  de/
    index.md
    about.md
```

## Hreflang Injection

The `I18nPlugin` runs in `after_compile` and automatically:

1. Scans the output directory for locale-prefixed subdirectories
2. Injects `<link rel="alternate" hreflang="...">` tags into every HTML page that exists in multiple locales
3. Adds an `x-default` alternate pointing to the default locale

Example injected HTML:

```html
<link rel="alternate" hreflang="en" href="https://example.com/en/about" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/about" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/about" />
```

The injection is **idempotent** — pages that already contain hreflang links are skipped.

## Accept-Language Negotiation

For the `sub_path` strategy, SSG generates a root redirect page that uses JavaScript `navigator.language` to detect the browser's preferred language and redirect to the matching locale path. This mimics `Accept-Language` negotiation for static sites.

## Per-Locale Sitemaps

The plugin generates locale-specific sitemaps with `xhtml:link` alternates:

- `sitemap-en.xml`
- `sitemap-fr.xml`
- `sitemap-de.xml`

Each sitemap entry includes alternate links to all other locales:

```xml
<url>
  <loc>https://example.com/en/about</loc>
  <xhtml:link rel="alternate" hreflang="fr"
    href="https://example.com/fr/about" />
  <xhtml:link rel="alternate" hreflang="de"
    href="https://example.com/de/about" />
</url>
```

## Language Switcher

SSG provides an HTML helper for generating a language switcher component. The switcher links to the same page in all available locales.

## Next Steps

- [Configuration](configuration.md) — full `ssg.toml` reference
- [SEO](seo.md) — hreflang impact on SEO
- [Deployment](deployment.md) — deploying multi-locale sites
