跳转至主内容
Version: 2.0.0-beta.4

i18n - 教程

本教程将带您浏览 Docusaurus i18n 系统基础。

我们将为新创立的英文 Docusaurus 站点添加简体中文翻译。

首先，使用 npx @docusaurus/init@latest init website classic 来创建新站点。（效果参见此处）

配置您的站点#

编辑 docusaurus.config.js 以添加对简体中文语言的 i18n 支持。

站点配置#

使用站点的 i18n 配置来声明 i18n 语言：

docusaurus.config.js
module.exports = {  i18n: {    defaultLocale: 'en',    locales: ['en', 'zh-cn'],  },};

主题配置#

添加 localeDropdown 类型的导航栏下拉框让用户选择语言：

docusaurus.config.js
module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'localeDropdown',          position: 'left',        },      ],    },  },};

运行网站#

以开发模式开启您的本地化站点，并使用您所选择的语言：

npm run start -- --locale zh-cn

您的站点可通过 http://localhost:3000/zh-cn/ 访问。

我们尚未添加任何译文，故网站大部分内容未被翻译。

tip

Docusaurus 为如 "下一页" 和 "上一页" 的通用主题标签提供了默认翻译。

请帮助我们完善这些默认译文。

caution

每个语言版本均是一个独立的单页应用程序：您无法同时开启所有语言的每一个 Docusaurus 站点。

翻译您的站点#

简体中文译文将置于 website/i18n/zh-cn。

Docusaurus 为模块化设计，因此每个内容插件均有自己的子文件夹。

note

复制文件后，请使用 npm run start -- --locale zh-cn 重启您的站点。

热加载功能在编辑现有文件时会发挥更好。

使用翻译 API#

打开首页，使用翻译 API：

src/pages/index.js
import React from 'react';import Layout from '@theme/Layout';import Link from '@docusaurus/Link';
// 高亮开始import Translate, {translate} from '@docusaurus/Translate';// 高亮结束
export default function Home() {  return (    <Layout>      <h1>        {/* 高亮开始 */}        <Translate>Welcome to my website</Translate>        {/* 高亮结束 */}      </h1>      <main>        {/* 高亮开始 */}        <Translate          id="homepage.visitMyBlog"          description="The homepage message to ask the user to visit my blog"          values={{blog: <Link to="https://docusaurus.io/blog">blog</Link>}}>          {'You can also visit my {blog}'}        </Translate>        {/* 高亮结束 */}
        <input          type="text"          placeholder={            // 高亮开始            translate({              message: 'Hello',              description: 'The homepage input placeholder',            })            // 高亮结束          }        />      </main>    </Layout>  );}
caution

Docusaurus 有意仅提供轻量级的翻译环境，且仅支持基础的、使用 ICU 信息格式子集的占位符改写功能。

文档网站多为静态，因此不需要进阶的 i18n 特性（复数、性别等）。 请使用如 react-intl 一类的库以获取高级功能。

翻译 JSON 文件#

JSON 译文文件用于不包含在 Markdown 文档中的其他一切内容：

  • React/JSX 代码
  • 导航栏布局及页脚标签
  • 文档侧边栏分类标签
  • ...

运行 write-translations 命令：

npm run write-translations -- --locale zh-cn

此命令将提取并初始化待翻译的 JSON 译文文件。

首页中的译文将被静态地从 React 源码中提取：

i18n/fr/code.json
{  "Welcome to my website": {    "message": "Welcome to my website",    "description": "The homepage welcome message"  },  "Hello": {    "message": "Hello",    "description": "The homepage input placeholder"  }}

插件及主题也会写入其自己的 JSON 译文文件，如：

i18n/fr/docusaurus-theme-classic/navbar.json
{  "title": {    "message": "My Site",    "description": "The title in the navbar"  },  "item.label.Docs": {    "message": "Docs",    "description": "Navbar item with label Docs"  },  "item.label.Blog": {    "message": "Blog",    "description": "Navbar item with label Blog"  },  "item.label.GitHub": {    "message": "GitHub",    "description": "Navbar item with label GitHub"  }}

翻译 i18n/zh-cn 中 JSON 文件的 message 属性，之后站点布局及首页即翻译完毕。

翻译 Markdown 文件#

官方的 Docusaurus 内容插件大量使用 Markdown/MDX 文件，并允许您进行翻译。

翻译文档#

将您文档的 Markdown 文件复制进 i18n/zh-cn/docusaurus-plugin-content-docs/current，并翻译：

mkdir -p i18n/zh-cn/docusaurus-plugin-content-docs/currentcp -r docs/** i18n/zh-cn/docusaurus-plugin-content-docs/current
信息

文档分版功能需要 current 文件夹：即每个文档版本需放置在不同的子文件夹中。

翻译博客#

将您博客的 Markdown 文件复制进 i18n/zh-cn/docusaurus-plugin-content-blog，并翻译：

mkdir -p i18n/zh-cn/docusaurus-plugin-content-blogcp -r blog/** i18n/zh-cn/docusaurus-plugin-content-blog

翻译页面#

将您页面的 Markdown 文件复制进 i18n/zh-cn/docusaurus-plugin-content-pages，并翻译：

mkdir -p i18n/fr/docusaurus-plugin-content-pagescp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pagescp -r src/pages/**.mdx i18n/fr/docusaurus-plugin-content-pages
caution

我们仅需要复制 .md 及 .mdx 文件，页面及 React 组件已通过 JSON 译文文件翻译完毕。

使用显式标题标识符#

默认情况下，Markdown 标题 ### Hello World 将自动生成标识符 hello-world。

其他文档则可通过 [link](#hello-world) 进行定向。

翻译后的标题 ### 你好世界 则将被标识为 你好世界。

由于您需要本地化所有锚定链接，故自动生成的标识符通常不适合本地化站点。

- [link](#hello-world).+ [link](#你好世界)
tip

对本地化站点，我们推荐使用显式标题标识符。

部署您的站点#

您可将您的站点部署在单个域名，或多个 (子) 域名下。

单域名部署#

执行下列命令：

npm run build

Docusaurus 将为每个语言版本构建一个单页面应用程序：

  • website/build：默认使用的英文语言
  • website/build/zh-cn：简体中文语言

您现可部署 build 文件夹至您所使用的静态托管解决方案上。

note

Docusaurus v2 网站使用此方案：

tip

静态托管托管商通常会将 /unknown/urls 重定向至 /404.html，同时还将显示英文版 404 错误页面。

配置您的托管商将 /zh-cn/* 重定向至 /zh-cn/404.html 以本地化您的 404 错误页。

但此功能不总是可用，其取决于您的托管商：比如 GitHub Pages 无法配置，但 Netlify 可以。

多域名部署#

您可为单一语言构建站点：

npm run build -- --locale zh-cn

Docusaurus 将不会添加 /zh-cn/ 网址前缀。

在您的静态托管托管商上：

  • 为每种语言创建一份部署版本
  • 使用 --locale 选项配置合适的构建指令
  • 为每份部署版本配置您选择的 (子) 域名
caution

由于 Github Pages 仅能进行单一部署，其不支持此功能。

混合部署#

您可将部分语言版本部署在子目录下，同时将其他语言版本部署在子域名上。

您也可以将每份语言版本部署在不同的子域名上，同时在 CDN 层面将子域名合并成单一域名：

  • 将您的网站部署为 zh-cn.docusaurus.io
  • 配置 CDN 从 docusaurus.io/zh-cn 拉取资源