🔌 VitePress i18n

VitePress i18n is a plugin for VitePress that makes it easy to translate text in the default theme and search tool. It translates the default layout with a simple setup and can be used in multiple projects without duplicate code.

• ⚡️ Optimized for the latest version of VitePress
• ⚡️ Lightweight bundle file size, zero dependencies
• ⚡️ TypeScript support

Installation

First, you may need to pre-configure VitePress before using this module.

We recommend using Node.js 18.x or higher. The VitePress i18n is written in ESM.

You will need to install the module using NPM or any other Node module package manager. The package should be installed in devDependencies as it is only used in the developer environment. Use the command below:

# via npm
$ npm i -D vitepress-i18n

# via yarn
$ yarn add -D vitepress-i18n

# via pnpm
$ pnpm i -D vitepress-i18n

How to use

VitePress i18n comes with a function to translate the general layout text (generateI18nLocale) and a function to translate the search interface (generateI18nSearch).

Each function must be called from a specific location in VitePress's configuration file. VitePress's configuration file is typically located at .vitepress/config.ts.

In VitePress' i18n, you can customize the locale key. For example, if you specify kor as the locale key for Korean translation, you can use a URL like /kor/docs/abc. This plugin requires you to properly configure defineLocales in the parameter so that it can tell it to translate a specific locale key into the language you specify.

For example, to translate what is specified as the kor key into Korean, add the following to the values in the defineLocales array: { label: 'kor', translateLocale: 'ko' }

The currently supported translation languages and translateLocale matching values are as follows:

(* = Currently using machine translation. Help us improve translation quality with a pull request!)

• English: en
• Korean (한국어): ko
• Chinese Simplified (简体中文): zhHans
• * Chinese Traditional (繁體中文): zhHant
• * Japanese (日本語): ja
• Spanish (Español): es
• Portuguese (Português): pt
• Russian (Русский): ru
• * Indonesian (Bahasa Indonesia): id
• * German (Deutsch): de
• * French (Français): fr
• * Vietnamese (Tiếng Việt): vi
• * Italian (Italiano): it

If a rootLocale value is specified, set the language key to root if the label language and the rootLocale value are the same. In the remaining areas, it does not need to be specified as root.

It will then use the same parameters that VitePress already uses. Note, however, that you must declare custom values for each of the keys you specify in defineLocales.

Methods: generateI18nLocale

Call this function with the locales option in VitePress's root config:

Example

export default defineConfig({
  locales: generateI18nLocale({
    defineLocales: [
      { label: 'en', translateLocale: 'en' },
      { label: 'ko', translateLocale: 'ko' }
    ],
    rootLocale: 'en',
    label: {
      en: 'English',
      ko: '한국어'
    },
    lang: {
      en: 'en-US',
      ko: 'ko-KR'
    },
    description: {
      en: 'Hello',
      ko: '안녕하세요'
    }
  })
});

Parameters

{
  defineLocales: DefineLocales[];
  rootLocale?: string;
  disableAutoSetLangValue?: boolean;
  debugPrint?: boolean;
  editLinkPattern?: string;
  label?: { [key: string]: string };
  link?: { [key: string]: string };
  lang?: { [key: string]: string };
  title?: { [key: string]: string };
  titleTemplate?: { [key: string]: string | boolean };
  description?: { [key: string]: string };
  head?: { [key: string]: HeadConfig[] };
  themeConfig?: { [key: string]: any };
}

Methods: generateI18nSearch

Call this function on the search option of VitePress's themeConfig:

Example

export default defineConfig({
  themeConfig: {
    search: generateI18nSearch({
      defineLocales: [{ label: 'ko', translateLocale: 'ko' }],
      rootLocale: 'en',
      provider: 'local'
    })
  }
});

Parameters

{
  defineLocales: DefineLocales[];
  rootLocale?: string;
  provider: 'local' | 'algolia';
  options?: LocalSearchOptions;
}

Contribute

You can report issues on GitHub Issue Tracker.

You can also request a pull to fix bugs and add frequently used features.

License

Copyright © 2024 CDGet <[email protected]> Released under the MIT license.