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

i18n - 教程

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

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

Initialize a new site with npx [email protected] website classic (like this one).

配置您的站点

编辑 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 为如 "下一页" 和 "上一页" 的通用主题标签提供了默认翻译

Please help us complete those default translations.

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/current
cp -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-blog
cp -r blog/** i18n/zh-cn/docusaurus-plugin-content-blog

翻译页面

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

mkdir -p i18n/fr/docusaurus-plugin-content-pages
cp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pages
cp -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 拉取资源