Package APIs

@i18n-micro/vitepress

Exported API of @i18n-micro/vitepress, generated from the source.

VitePress bindings for i18n-micro — runtime dictionaries, MD components, and locale switcher.

Entry points: @i18n-micro/vitepress, @i18n-micro/vitepress/config, @i18n-micro/vitepress/node, @i18n-micro/vitepress/theme.

@i18n-micro/vitepress

Functions

createI18n

Universal VitePress i18n: Vue plugin + path helpers + enhanceApp sync. Path methods are the router adapter’s own functions (no wrapper layer).

function createI18n(options: CreateI18nOptions): CreateI18nResult

See CreateI18nOptions · CreateI18nResult

getLocaleFromPath

Detect i18n locale code from a URL path (prefix_except_default). Path prefixes are VitePress locale keys; return value is the i18n code. Pass base when the path may include VitePress site.base (SSG).

function getLocaleFromPath(
  path: string,
  localeCodes: string[],
  defaultLocale: string,
  localeKeyToCode?: Record<string, string>,
  base?: string,
): string

messagesFromGlob

Tiny helper if you still prefer import.meta.glob instead of defineI18nTheme. Only unwraps Vite module namespaces — dictionaries with a default key stay intact.

function messagesFromGlob(
  modules: Record<string, { default: Translations; } | Translations>,
): Record<string, Translations>

See Translations

routeNameFromPath

Route name for page-scoped dictionaries (/guide/demo → guide-demo). Strips VitePress URL prefixes (keys), not only raw i18n codes.

When defaultLocale is omitted (legacy 2-arg call), any segment that matches a listed locale code is stripped — callers must not rely on localeCodes[0] as default.

function routeNameFromPath(
  path: string,
  localeCodes: string[],
  defaultLocale?: string,
  localeKeyToCode?: Record<string, string>,
  base?: string,
): string

stripSiteBase

Strip VitePress site.base from a path. Leaves query/hash intact. No-op when base is missing or /.

function stripSiteBase(path: string, base?: string): string

Types

CreateI18nOptions

interface CreateI18nOptions

CreateI18nResult

type CreateI18nResult = I18nPlugin & PathMethods & { … }
i18n
I18nPlugin['global'] & PathMethods required
Same as .global (VueI18n + path methods).
enhanceApp
(ctx: { app: App; router: VitePressRouterLike; siteData?: Ref<VitePressSiteDataLike> | VitePressSiteDataLike; }) => void required

See I18nPlugin · PathMethods

PathMethods

Path helpers exposed on createI18n instances (slice of the router adapter).

type PathMethods = Pick<VitePressRouterAdapter, 'localizePath' | 'switchLocalePath' | 'getLocaleFromPath' | 'removeLocaleFromPath' | 'routeNameFromPath'>

VirtualI18nConfig

interface VirtualI18nConfig

VitePressSiteDataLike

interface VitePressSiteDataLike
locales
Record<string, { lang?: string; link?: string; label?: string; }>

VitePressUserConfigLike

Minimal VitePress / Vite user config shape we merge into. Avoid importing vitepress types so the package stays usable as a pure library dep.

interface VitePressUserConfigLike
base
string
locales
Record<string, unknown>
themeConfig
Record<string, unknown> | null
transformHead
(...args: any[]) => any
transformPageData
(...args: any[]) => any
vite
{ plugins?: Plugin[] | Plugin[][]; ssr?: { noExternal?: string | true | Array<string | RegExp>; [key: string]: unknown; }; [key: string]: unknown; }
[key: string]
unknown

WithI18nOptions

interface WithI18nOptions extends CreateI18nOptions
translationDir
string
Default'locales' · Directory with locale JSON (en.json, pages/guide/demo/en.json, …), relative to Vite root (VitePress content / docs root). Used by virtual:i18n-micro/messages.
disablePageLocales
boolean
Defaultfalse · When true, treat pages/** as root-level dictionaries.
warnOnLocaleMismatch
boolean
Defaulttrue · When true, logs a warning if VitePress locales keys do not align with configured i18n locale codes.
i18nRouting
boolean
Defaulttrue · Inject themeConfig.i18nRouting from adapter options + config.base. Set false to skip. Skipped automatically when themeConfig.i18nRouting is already set.
meta
boolean
Defaulttrue when `metaBaseUrl` is set, otherwise false · Emit i18n SEO tags via transformHead (canonical, hreflang, og:locale…) — Nuxt meta / plugin 02.meta analogue. Absolute link tags require metaBaseUrl.
metaBaseUrl
string
Public origin without trailing slash (https://example.com). Same role as Nuxt metaBaseUrl.
hreflangBaseLanguage
boolean
Defaultfalse · Also emit bare-language hreflang from iso (Nuxt hreflangBaseLanguage).
canonicalQueryWhitelist
string[]
Default[] · Query keys kept on canonical / alternate URLs.

See CreateI18nOptions

Re-exports

Declared in another package of this repository and documented on its page.

@i18n-micro/vitepress/config

Also exports, as @i18n-micro/vitepress does: VirtualI18nConfig · VitePressUserConfigLike · WithI18nOptions.

Functions

buildVitePressLocaleHead

Build i18n SEO head for VitePress — same tags as Nuxt useLocaleHead / plugin 02.meta (canonical, hreflang, x-default, og:locale / og:url / alternates).

Framework-agnostic pure function; wired automatically by withI18n when meta is on.

function buildVitePressLocaleHead(
  options: BuildVitePressLocaleHeadOptions,
): VitePressLocaleHeadObject

See BuildVitePressLocaleHeadOptions · VitePressLocaleHeadObject

buildVitePressLocales

Build VitePress config.locales from i18n-micro Locale[]. Default locale becomes root (no URL prefix); others get /{key}/.

function buildVitePressLocales(
  locales: Locale[],
  defaultLocale: string,
  options?: BuildVitePressLocalesOptions,
): Record<string, VitePressLocaleEntry>

See Locale · BuildVitePressLocalesOptions · VitePressLocaleEntry

relativePathToRoutePath

Convert VitePress pageData.relativePath to a route path (cleanUrls-style).

function relativePathToRoutePath(relativePath: string): string

warnLocaleMismatch

function warnLocaleMismatch(
  config: VitePressUserConfigLike,
  options: WithI18nOptions,
): void

See VitePressUserConfigLike · WithI18nOptions

withI18n

VitePress config helper: virtual modules + optional i18nRouting / SEO head.

Registers:

  • virtual:i18n-micro/config
  • virtual:i18n-micro/messages (from translationDir, default locales/)

By default also sets themeConfig.i18nRouting (pass i18nRouting: false to skip). Pair with defineI18nTheme(DefaultTheme) from @i18n-micro/vitepress/theme. Import from @i18n-micro/vitepress/config (Node / config files only).

function withI18n<T extends VitePressUserConfigLike>(
  config: T,
  options: WithI18nOptions,
): T

See VitePressUserConfigLike · WithI18nOptions

Types

BuildVitePressLocaleHeadOptions

interface BuildVitePressLocaleHeadOptions

BuildVitePressLocalesOptions

interface BuildVitePressLocalesOptions
localeKeyToCode
Record<string, string>
Map VitePress locale keys → i18n codes (root → default). When a non-default code maps to a short VP key (fr → fr-FR), the URL prefix / config key uses the VP key.

VitePressHeadTuple

VitePress HeadConfig tuple (tag + attrs).

type VitePressHeadTuple = [
  string,
  Record<string, string>
]

VitePressLocaleEntry

Minimal VitePress locales entry used by the default theme language menu.

interface VitePressLocaleEntry
label
string required
lang
string required
link
string

VitePressLocaleHeadObject

interface VitePressLocaleHeadObject
htmlAttrs
{ lang?: string; dir?: 'ltr' | 'rtl' | 'auto'; } required
head
VitePressHeadTuple[] required
Ready for transformHead / frontmatter.head.

@i18n-micro/vitepress/node

Also exports, as @i18n-micro/vitepress/config does: buildVitePressLocales · BuildVitePressLocalesOptions · VitePressLocaleEntry.

Functions

createI18n

Node createI18n (@i18n-micro/node) + VitePress path methods from the router adapter.

function createI18n(options: CreateI18nOptions): NodeI18n

See CreateI18nOptions · NodeI18n

Types

CreateI18nOptions

interface CreateI18nOptions extends I18nOptions
locales
Locale[] | string[]
Locales for path helpers (localizePath, …). Defaults to [{ code: locale }].
defaultLocale
string
localeKeyToCode
Record<string, string>
base
string

See I18nOptions

NodeI18n

type NodeI18n = I18n & PathMethods

See I18n · PathMethods

Re-exports

Declared in another package of this repository and documented on its page.

@i18n-micro/vitepress/theme

Functions

defineI18nTheme

Zero-boilerplate theme wiring. Requires withI18n(...) in .vitepress/config so virtual config + messages modules exist.

Uses static virtual:i18n-micro/* imports so VitePress SSG can rewrite them. Import this helper from @i18n-micro/vitepress/theme (not the root entry) so Node config evaluation never loads virtual modules.

function defineI18nTheme<T extends Theme>(base: T, options?: DefineI18nThemeOptions): T

import DefaultTheme from 'vitepress/theme'
import { defineI18nTheme } from '@i18n-micro/vitepress/theme'

export default defineI18nTheme(DefaultTheme)

See DefineI18nThemeOptions

Types

DefineI18nThemeOptions

interface DefineI18nThemeOptions

Generated from the TypeScript sources and their JSDoc by pnpm run docs:generate. Back to all packages · Integration guides

@i18n-micro/utils

Exported API of @i18n-micro/utils, generated from the source.

@i18n-micro/vue

Exported API of @i18n-micro/vue, generated from the source.