Configuration

Core API Only

For framework integration guide, see Internationalization.

Define Config

Fumadocs core provides necessary middleware and utilities for i18n support.

You can define a config to share between utilities.

lib/i18n.ts

import { defineI18n } from 'fumadocs-core/i18n';

export const i18n = defineI18n({
  defaultLanguage: 'en',
  languages: ['en', 'cn'],
});

Hide Locale Prefix

To hide the locale prefix (e.g. /en/page -> /page), use the hideLocale option.

import { defineI18n } from 'fumadocs-core/i18n';

export const i18n = defineI18n({
  defaultLanguage: 'en',
  languages: ['en', 'cn'],
  hideLocale: 'default-locale',
});

Mode	Description
`always`	Always hide the prefix, detect locale from cookies
`default-locale`	Only hide the default locale
`never`	Never hide the prefix (default)

Using always

On always mode, locale is stored as a cookie (set by the middleware), which isn't optimal for static sites.

This may cause undesired cache problems, and need to pay extra attention on SEO to ensure search engines can index your pages correctly.

Fallback Language

The fallback language to use when translations are missing for a file, default to your defaultLanguage.

It accepts one of the languages in your languages array.

import { defineI18n } from 'fumadocs-core/i18n';

export const i18n = defineI18n({
  languages: ['en', 'cn'],
  defaultLanguage: 'en',
  // Chinese variant is used if a file is missing in English
  fallbackLanguage: 'cn',
});

To disable the fallback behaviour, set it to null:

import { defineI18n } from 'fumadocs-core/i18n';

export const i18n = defineI18n({
  languages: ['en', 'cn'],
  defaultLanguage: 'en',
  fallbackLanguage: null,
});

When disabled, no fallback will be used (including meta.json). You can still create a shared file for every locale with $:

my-page.$.md

meta.$.json

Define Config

Hide Locale Prefix

Fallback Language

On this page