feat: support i18n

[brc-dd]

Breaking Changes

• Legacy i18n stuff is removed/replaced.

  • localePath is removed from useData(). One can have similar functionality using localeIndex or lang property.

• For people using the default theme, themeConfig.localeLinks is removed in favor of locales.

  Change:

  themeConfig: {
    localeLinks: {
        text: 'English',
        items: [
          { text: '简体中文', link: 'https://cn.vitejs.dev' },
          { text: '日本語', link: 'https://ja.vitejs.dev' },
          { text: 'Español', link: 'https://es.vitejs.dev' }
        ]
    }
  }

  to:

  locales: {
    root: { label: 'English' },
    zh: { label: '简体中文', link: 'https://cn.vitejs.dev' },
    ja: { label: '日本語', link: 'https://ja.vitejs.dev' },
    es: { label: 'Español', link: 'https://es.vitejs.dev' }
  }

• There are internal changes in Algolia Search and Carbon Ads components.

Features

To use in-built i18n features, one need to create a file structure as following:

docs/
├─ es/
│  ├─ baz.md
├─ fr/
│  ├─ bar.md
├─ foo.md

Then in docs/.vitepress/config:

defineConfig({
  // shared properties and other top-level stuff...
  
  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    fr: {
      label: 'French',
      lang: 'fr', // optional, will be added  as `lang` attribute on `html` tag
      link: '/fr/guide' // default /fr/ -- shows on navbar translations menu, can be external

      // other locale specific properties...
    }
  }
})

The following properties can be overridden for each locale (including root):

interface LocaleSpecificConfig<ThemeConfig = any> {
  lang?: string
  dir?: string
  title?: string
  titleTemplate?: string | boolean
  description?: string
  head?: HeadConfig[] // will be merged with existing head entries, duplicate meta tags are automatically removed
  themeConfig?: ThemeConfig // will be shallow merged, common stuff can be put in top-level themeConfig entry
}

• All of the labels (placeholder texts) of default theme can now be customized. Refer DefaultTheme.Config type for details.

Linked Issues

• fixes Add internationalization feature #631
• fixes Define a base type for ThemeConfig instead of any #628
• fixes Make it possible to translate some labels #955
• fixes Default language on it's own directory like other languages #291 (see notes below)
• fixes How to set the text direction? #902 (see notes below)
• fixes [i18n] allow translating docsearch labels #1381 (see notes below)
• fixes [i18n]: always naviageto init page when language change not the corresponding URL #1253 (see notes below)

Todo

• Support RTL scripts: How to set the text direction? #902
  • Added option to specify attribute.
  • But track this separately as it needs modification in theme too.
    • done via feat(theme): add rtlcss directive #1512, thanks to @sadeghbarati
• Test Algolia DocSearch's facetFilters option (Help needed. I don't have an account to test that.)
  • Test/fix __ALGOLIA__ and __CARBON__ logic. (See notes below.)
• Allow overriding Algolia options based on locale. Support Algolia's i18n options.
  • Related implementations:
    • https://github.com/vuejs/vitepress/blob/b1983806188e54acd57c2acba97de2424d971181/src/client/theme-default/components/AlgoliaSearchBox.vue
    • https://github.com/vuepress/vuepress-next/blob/main/ecosystem/plugin-docsearch/src/client/components/Docsearch.ts
    • A question about i18n configuration algolia/docsearch#599
    • Ability to update options on the fly, or exposing an API to re-initialize docsearch algolia/docsearch#608
• Write (and update) docs.
• Test with Vue and Vite docs if something other than the ones mentioned here breaks. (Likely there will be a mess in vue/theme because of types. Probably will have to keep theme config any by default, and typing it specifically in the default theme. Can also use module augmentation. Will take a look what's cleaner and require least change in other projects. Reverted.)
• Check broken links/features after setting some base.
• Somehow try fixing [i18n]: always naviageto init page when language change not the corresponding URL #1253 (a very basic implementation can be to just provide a map from one address to another if the url is different).

I was going through VuePress' implementation, and I think some other things can be done or need testing:

• Check if the back to home link of the 404 page is locale specific.
• Allow setting 404 text and other stuff in that page?
• Allow customizing text of containers at theme level?
  • Markdown renderer is currently not customizable based on theme. We can use something like file name to resolve locale, but I don't think that much work is worth it. Users can still override the labels. Also, IMO the use of default containers is quite limited in projects. We can track this separately if there is significant demand.
• Optimize DocSearch update? (They are modifying facetFilters in-place to prevent re-initialization in case only the language has changed. But IG most of the projects will be changing other stuff like placeholder/translations too if they are using locales with Algolia. Not sure if this optimization will have any significant impact.)

Notes

• locales.root is not required if there is no document at root level.

  This is a perfectly fine structure:

  docs/
  ├─ en/
  │  ├─ foo.md
  ├─ es/
  │  ├─ baz.md
  ├─ fr/
     ├─ bar.md
  

  However, VitePress won't redirect / to /en/ by default. You'll need to configure your server for that. On Netlify, the configuration (docs/public/_redirects) may look similar to this:

  /*  /es/:splat  302  Language=es
  /*  /fr/:splat  302  Language=fr
  /*  /en/:splat  302
  

  Pro tip: If using the above approach, you can use nf_lang cookie to persist user's language choice. A very basic way to do this is register a watcher inside setup function of custom theme:

  // docs/.vitepress/theme/index.ts
  
  export default {
    ...DefaultTheme,
    setup() {
      const { lang } = useData()
      watchEffect(() => {
        if (inBrowser) {
          document.cookie = `nf_lang=${lang.value}; expires=Mon, 1 Jan 2024 00:00:00 UTC; path=/`
        }
      })
    }
  }

  For a complete example visit https://github.com/brc-dd/vite-docs (deployed at https://gleeful-rugelach-418cf0.netlify.app/). It's a test repo with combined Vite's docs.

• For testing purposes you can use these changes by running pnpm add -D vitepress@npm:@brc-dd/vitepress@next

• Config file can now be stored at docs/.vitepress/config/index.ts too. It allows you to write separate config files for locales inside the same directory and export them from index. (example)

• Don't override themeConfig.algolia and themeConfig.carbonAds at locale-level. To use multilingual DocSearch, you can have some configuration like this:

  Click to expand

  defineConfig({
    // ...
    themeConfig: {
    // ...
  
      algolia: {
        appId: '34YFD9IUQ2',
        apiKey: '9a9058b8655746634e01071411c366b8',
        indexName: 'vuepress',
        searchParameters: {
          facetFilters: ['tags:v2']
        },
        locales: {
          zh: {
            placeholder: '搜索文档',
            translations: {
              button: {
                buttonText: '搜索文档',
                buttonAriaLabel: '搜索文档'
              },
              modal: {
                searchBox: {
                  resetButtonTitle: '清除查询条件',
                  resetButtonAriaLabel: '清除查询条件',
                  cancelButtonText: '取消',
                  cancelButtonAriaLabel: '取消'
                },
                startScreen: {
                  recentSearchesTitle: '搜索历史',
                  noRecentSearchesText: '没有搜索历史',
                  saveRecentSearchButtonTitle: '保存至搜索历史',
                  removeRecentSearchButtonTitle: '从搜索历史中移除',
                  favoriteSearchesTitle: '收藏',
                  removeFavoriteSearchButtonTitle: '从收藏中移除'
                },
                errorScreen: {
                  titleText: '无法获取结果',
                  helpText: '你可能需要检查你的网络连接'
                },
                footer: {
                  selectText: '选择',
                  navigateText: '切换',
                  closeText: '关闭',
                  searchByText: '搜索提供者'
                },
                noResultsScreen: {
                  noResultsText: '无法找到相关结果',
                  suggestedQueryText: '你可以尝试查询',
                  reportMissingResultsText: '你认为该查询应该有结果？',
                  reportMissingResultsLinkText: '点击反馈'
                }
              }
            }
          }
        }
      }
    }
  })

  These options can be overridden. Refer Algolia's docs on what they do.

• For RTL support, specify dir: 'rtl' in config and use some RTLCSS PostCSS plugin (https://github.com/MohammadYounes/rtlcss, https://github.com/vkalinichev/postcss-rtl, https://github.com/elchininet/postcss-rtlcss). You'll need to configure your PostCSS plugin to use :where([dir="ltr"]) and :where([dir="rtl"]) as prefixes to prevent CSS specificity issues.

• Changing locale to say zh will change the URL from /foo (or /en/foo/) to /zh/foo. You can disable this behavior by setting themeConfig.i18nRouting to false.

[VoVAllen]

any plan to merge this?

[PierW]

@yyx990803 hope to see this as soon as possible

[kiaking]

We're working on it. Almost done. We're checking if this wouldn't break any ecosystem like Vue and Vite docs. Stay tuned!

[PierW]

Finally! thank you! ❤️

[awxiaoxian2020]

@brc-dd Could you please add docs for outline.label?