---
title: "Internationalization"
description: "Create multi-language documentation with Docus built-in i18n support."
canonical_url: "https://docus.dev/en/concepts/internationalization"
---
# Internationalization

> Create multi-language documentation with Docus built-in i18n support.

Docus introduces **native internationalization support** based on the `@nuxtjs/i18n` module, allowing you to create documentation in multiple languages with automatic routing and content management.

## Features

- **Built-in i18n module**: Native integration with `@nuxtjs/i18n`
- **Dynamic locale routing**: Automatic URL prefixing with language codes (`/en/docs`, `/fr/docs`)
- **Content collections per locale**: Separate content management for each language
- **Language switcher**: Built-in component for switching between locales
- **Single-language configuration**: Simple locale configuration for single-language sites via `app.config.ts`

## Single Language Configuration

If you're building documentation in a single language (without the full `@nuxtjs/i18n` module), you can configure the locale through `app.config.ts`. This is useful for setting the language for UI components and localizing built-in strings.

```ts [app.config.ts]
export default defineAppConfig({
  docus: {
    locale: 'fr', // Set your locale (default: 'en')
  }
})
```

## Multi-Language Setup

For multi-language documentation, use the full `@nuxtjs/i18n` integration as described below.

### Setup an existing project

To enable i18n in your Docus project, add the `@nuxtjs/i18n` module to your `nuxt.config.ts` and define your locales:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English' },
      { code: 'fr', name: 'Français' },
    ],
  }
})
```

<warning>

Docus overrides the `@nuxtjs/i18n` strategy to `prefix`.

</warning>

## Create a new project with i18n template

When creating a new project, you can choose the i18n template for pre-configured internationalization:

```bash [Terminal]
npx create-docus my-docs -t i18n
```

## Directory Structure

When i18n is enabled, organize your content by locale in the `content/` directory:

```bash
content/
├── en/                    # English content
│   ├── index.md          # English homepage
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── configuration.md
│   └── guide/
│       └── advanced.md
├── fr/                    # French content
│   ├── index.md          # French homepage
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── configuration.md
│   └── guide/
│       └── advanced.md
```

<warning>

Each locale should mirror the same directory structure to maintain consistent navigation across languages.

</warning>

## Locale fallback

Docus warns and skips any locale that does not exist in your `content/` directory. Missing locales are not registered.

<tip>

This is especially helpful when you extend Docus and use `@nuxtjs/i18n` for the rest of your site, but only want the docs in a subset of languages.

</tip>

Docus detects locales from your nuxt config:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    locales: ['en', 'fr', 'ja'],
    defaultLocale: 'en'
  }
})
```

But only register it based on your `content/` folder structure:

```bash
content/
├─ en/           # registered ✅
├─ fr/           # registered ✅ (if present)
└─ ja/           # skipped 🚫 (if missing)
```

If a user requests a missing docs locale, Docus redirects to the **default locale**.

<warning>

You must set a `defaultLocale` in your i18n config and ensure it exists under `content/<defaultLocale>`

</warning>


## Sitemap

See the full [sitemap](https://docus.dev/sitemap.md) for all pages.