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
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
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 (베트남어):vi
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
.
Call this function with the locales
option in VitePress's root config:
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: '안녕하세요'
}
})
});
{
defineLocales: DefineLocales[];
rootLocale?: string;
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 };
}
Call this function on the search
option of VitePress's themeConfig
:
export default defineConfig({
themeConfig: {
search: generateI18nSearch({
defineLocales: [{ label: 'ko', translateLocale: 'ko' }],
rootLocale: 'en',
provider: 'local'
})
}
});
{
defineLocales: DefineLocales[];
rootLocale?: string;
provider: 'local' | 'algolia';
options?: LocalSearchOptions;
}
You can report issues on GitHub Issue Tracker.
You can also request a pull to fix bugs and add frequently used features.
Copyright © 2024 CDGet <jooy2.contact@gmail.com> Released under the MIT license.