Languages (Multi-language Architecture)

Methanol implements multi-language support through a directory-based architecture. When a directory index page includes a lang field, that directory is identified as a language entry point. This provides a lightweight method for organizing translations without the complexity of an external i18n system.

Core Mechanism

• An index.mdx file containing a lang property defines the Language Root for its directory.
• The lang property value is utilized as the display label within the language selector.
• The system determines the active state by matching the current URL route to the nearest language root.
• The HTML lang attribute is derived from langCode (including the root index); if undefined, the directory name is used as a fallback.

Directory structure example:

pages/
  index.mdx          # Default language root
  zh/
    index.mdx        # Chinese language root
    guide.mdx
  fr/
    index.mdx        # French language root
    guide.mdx

Frontmatter example:

---
title: English
lang: English
langCode: en
isRoot: true
hidden: true
---

Language Selector Integration

The standard theme automatically displays a language selector upon detecting directory index pages with a defined lang property (including the site root /). It utilizes:

• lang for the display label.
• ctx.language to determine the currently active selection.

Navigation Scoping

Language roots are typically paired with isRoot: true to scope the navigation tree to that specific directory.

Note: isRoot pages are concealed from navigation by default. Set hidden: false if you wish for the language root to appear within the sidebar.

This mechanism enables independent navigation structures for each supported language.

The ctx.languages Data Structure

ctx.languages is an array of language entry objects aggregated from directory index pages. When generating links, always use routeHref to ensure the site.base prefix is correctly applied.

{
	routePath: '/zh/',
	routeHref: '/zh/',
	label: '简体中文',
	code: 'zh'
}

The site root language is included in this array if the root index.mdx defines a lang property.

Implementation Tips

• Visibility: isRoot pages are hidden by default; utilize hidden: false to display a language root in the sidebar.
• Symmetry: Maintain matching paths across languages (e.g., /guide and /ja/guide) for a predictable and manageable structure.
• Scoping: Applying isRoot: true to language index pages prevents default language entries from appearing redundantly in the route list while maintaining proper navigation scope.