Use Crowdin to Translate & Localize VitePress

本文中文版本可用：使用 Crowdin 翻译和本地化 VitePress。

VitePress is a Vite & Vue powered static site generator. I used that in several document sites of my projects, such as CranSurvey, Detalk.js.

Recently, I have been considering translating documents, because CranSurvey is a project that supports multiple languages.

When I started building a multiple languages document site, I realized this was not an easy job. The main project of CranSurvey is using Crowdin to translate i18n files. What about using it on the VitePress site?

Link Project

First, we need to create a Crowdin account. That's free, (and I have GitHub Student Package).

Then, we need to create a project in Crowdin.

Choose the Project name that you prefer, make it public or private, then select the source language and the target languages.

After creating the project, we'll need to click the Integrations tab to Integrate with our GitHub repository.

Then we click Add Repository and choose the source and translation files mode. Select the repository and branch that is in your account and that you want to link with.

Crowdin may say that there is a problem that you need to fix, we should click on that and start our branch configuration.

Branch Configuration

This configuration is different based on your project. If you have a project like mine, that has default languages in the main folder, and other languages in separated folders named with locale string with underscore, you can have the same configurations.

I also ignored some project files such as package.json, yarn.lock, and .vitepress folders.

Now, we have already configured the branch. You can also see the configuration in the crowdin.yml file:

files:
  - source: /**/**.md
    ignore:
      - /%locale_with_underscore%
      - /.vitepress/
      - yarn.lock
      - package.json
      - .gitignore
    translation: /%locale_with_underscore%/%original_path%/%original_file_name%

Translate Files

Then, we can go back to the Dashboard. If you already configured your Machine Translator API Key, you can do the Pre-Translation.

Click via MT, select the provider that you want, select all the target languages and sources, then click pre-translation via MT.

After pre-translation, you can go to the editor to translate or you can go back to your GitHub repository and merge the pull request

Now, we have the translation files.

VitePress Configuration

Go to .vitepress/config.mts (or other formats) and configure the site configs.

export default defineConfig({
  // ...
  locales: {
    root: {
      label: 'English (US)',
      lang: 'en_US',
    },
    zh_CN: {
      label: '中文(简体)',
      lang: 'zh_CN',
      link: '/zh_CN/',
    },
    zh_TW: {
      label: '中文(繁體)',
      lang: 'zh_TW',
      link: '/zh_TW/',
    },
    // ... other languages
  },
  // ...
})

Now we're done, you can visit your site and check.