Internationalization (i18n)

Trellis Docs supports publishing your documentation in multiple languages. The internationalization (i18n) system is opt-in — when disabled (the default), your site works exactly as a single-language project with zero overhead.

How it works

• Each locale gets its own content directory under content/i18n/<code>/docs/
• The default locale's content lives in content/docs/ as usual
• Non-default locales are prefixed in the URL: /es/getting-started/, /ja/introduction/
• If a translation is missing, Trellis Docs falls back to the default locale's content and shows a banner
• A globe dropdown in the navbar lets readers switch languages

Enable i18n

Open config/site.ts and update the i18n block:

i18n: {
  enabled: true,
  defaultLocale: 'en',
  locales: [
    { code: 'en', name: 'English', dir: 'ltr' },
    { code: 'es', name: 'Español', dir: 'ltr' },
    { code: 'ja', name: '日本語', dir: 'ltr' },
  ],
},

Content structure

After enabling i18n, create translation directories under content/i18n/:

my-project/
├── content/
│   ├── docs/                      # Default locale (English)
│   │   ├── getting-started.mdx
│   │   └── guides/
│   │       └── deployment.mdx
│   └── i18n/
│       ├── es/
│       │   └── docs/              # Spanish translations
│       │       ├── getting-started.mdx
│       │       └── guides/
│       │           └── deployment.mdx
│       └── ja/
│           └── docs/              # Japanese translations
│               └── getting-started.mdx

The file paths inside each locale's docs/ directory must mirror the default locale's structure. For example, if content/docs/guides/deployment.mdx exists, the Spanish translation goes at content/i18n/es/docs/guides/deployment.mdx.

Translation fallback

You don't need to translate every page at once. When a page hasn't been translated to the requested locale, Trellis Docs automatically:

1. Loads the default locale's content instead
2. Displays a banner at the top of the page:

This page has not been translated to Español yet. You are viewing the English version.

This means all routes work for every locale — even before you've written a single translation.

URL routing

The default locale has no prefix in URLs. Non-default locales are prefixed with their code:

When versioning is also enabled, the locale prefix comes first:

Locale switcher

When i18n is enabled, a globe icon dropdown appears in the navbar. Select any configured locale from the dropdown to switch languages. The switcher preserves the current page — switching from /es/guides/deployment/ to Japanese navigates to /ja/guides/deployment/.

Search

Trellis Docs automatically partitions the search index by locale. When a reader searches on the Spanish version of the site, results come only from Spanish content (falling back to English for untranslated pages).

SEO

Trellis Docs automatically adds hreflang alternate links to page metadata when i18n is enabled. This tells search engines about the relationship between translations of the same page.

Frontmatter

Translation files use the same frontmatter fields as the default locale. Translate the title and description fields:

---
title: Primeros Pasos
description: Instala y configura tu sitio de documentación con Trellis.
keywords: [inicio, configuración, instalación]
---

Adding a new locale

1. Add the locale to the locales array in config/site.ts.
2. Create the directory content/i18n/<code>/docs/.
3. Start translating pages — untranslated pages fall back automatically.
4. Run npm run build to verify all routes generate correctly.