Docusaurus国际化(i18n)

  • 修改 docusaurus.config.js 加入 zh-CN locale(这里以我要支持的中文为例)

配置 docusaurus.config.js locale
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'zh-CN'],
  },

备注

文件复制到 i18n/zh-CN 对应目录目录进行翻译，每个locale和plugin有自己的 i18n 子目录，其目录格式是:

每个locale和plugin有自己的 i18n 子目录
website/i18n/[locale]/[pluginName]/...

对于 Docusaurus多文档 使用了插件 plugin-content-docs ，以及 plugin-content-blog (BLOG)，那么需要具备如下目录结构:

i18n 目录结构
website/i18n
└── zh-CN
    ├── code.json  # Any text label present in the React code
    │              # Includes text labels from the themes' code
    ├── docusaurus-plugin-content-blog # translation data the blog plugin needs
    │   └── 2020-01-01-hello.md
    │
    ├── docusaurus-plugin-content-docs # translation data the docs plugin needs
    │   ├── current
    │   │   ├── doc1.md
    │   │   └── doc2.mdx
    │   └── current.json
    │
    └── docusaurus-theme-classic # translation data the classic theme needs
        ├── footer.json   # Text labels in your footer theme config
        └── navbar.json   # Text labels in your navbar theme config

备注

这里的 i18n/zh-CN 以及目录下的 .json 文件可以通过 docusaurus write-translations [siteDir]

  • 创建 i18n/en 和 i18n/zh-CN 目录结构以及对应 .json 文件

i18n/en 和 i18n/zh-CN 目录结构以及对应 .json 文件
docs_dir="/home/admin/docs/github/huataihuang/docs.cloud-atlas.dev"

#npm run docusaurus write-translations /Users/admin/docs/github/huataihuang/docs.cloud-atlas.dev
npm run docusaurus write-translations $docs_dir -- --locale zh-CN

此时显示信息(以 zh-CN 为例:

i18n/zh-CN 目录结构以及对应 .json 文件

> docs-cloud-atlas-dev@0.0.0 docusaurus
> docusaurus write-translations /Users/admin/docs/github/huataihuang/docs.cloud-atlas.dev --locale zh-CN

[INFO] 81 translations will be written at "i18n/zh-CN/code.json".
[INFO] 6 translations will be written at "i18n/zh-CN/docusaurus-theme-classic/navbar.json".
[INFO] 10 translations will be written at "i18n/zh-CN/docusaurus-theme-classic/footer.json".
[INFO] 1 translations will be written at "i18n/zh-CN/docusaurus-plugin-content-docs-discovery/current.json".
[INFO] 3 translations will be written at "i18n/zh-CN/docusaurus-plugin-content-blog/options.json".
[INFO] 4 translations will be written at "i18n/zh-CN/docusaurus-plugin-content-docs/current.json".

这里实际完成后的目录结构(因为 Docusaurus多文档 )，注意 docusaurus-plugin-content-docs 下有一个 current 子目录

Docusaurus多文档 环境的 i18n 目录
.
└── zh-CN
    ├── code.json
    ├── docusaurus-plugin-content-blog
    │   ├── 2019-05-28-first-blog-post.md
    │   └── options.json
    ├── docusaurus-plugin-content-docs
    │   ├── current
    │   │   └── intro.md
    │   └── current.json
    ├── docusaurus-plugin-content-docs-discovery
    │   ├── current
    │   │   └── intro.md
    │   └── current.json
    └── docusaurus-theme-classic
        ├── footer.json
        └── navbar.json

备注

这里使用了参数 --locale zh-CN 则会创建和输出 zh-CN 对应locale目录结构和json文件，如果没有参数则会生成 en 对应的locale目录结构。

实践发现，需要同时为所有语言创建好目录结构(并且对应复制好文件进行后续翻译修改)，否则切换语言会显示文件找不到

  • 启动(开发环境每次只能启动一个locale):

启动 zh-CN locale 服务测试
npm run start -- --locale zh-CN --host 0.0.0.0

  • 添加locale下拉菜单: 为了能够在不同语言间切换，修订 docusaurus.config.js :

修订 docusaurus.config.js 添加语言切换下拉菜单
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
        },
      ],
    },
  },
};

备注

i18n 实际上是采用 优先覆盖 模式，也就是:

  • 如果 i18n/zh-CN/docusaurus-plugin-content-docs/current 目录下有对应翻译文件 intro.md ，就会显示覆盖默认的 intro.md

  • 但是如果没有翻译文件，则会继续显示 docs 目录的对应默认文件

注意项

  • 在开发环境中，每次只能测试一种 locale ，也就是如果运行了 --locale zh-CN ，则全程只能测试该locale的页面点击，当使用 locale下拉菜单 点击 English ，会出现 找不到页面 报错。这是正常的，当需要测试 English locale，需要在运行启动时去除 --locale zh-CN 以默认 en 运行

  • 我最初在配置 docusaurus.config.js 只设置了 routeBasePath 为 arch ，但是依然保留了默认的 path (也就是 docs )，现在我统一为 architecture (架构)，同时设置 path 和 routeBasePath

备注

我的实践配置见 multi docs, i18n (commit) (包含 Docusaurus多文档 )

参考