跳到主要内容

i18n - 教程

本教程将引导您了解 Docusaurus i18n 系统 的基础知识。

我们将为一个新初始化的英文 Docusaurus 网站添加法语翻译。

使用 npx create-docusaurus@latest website classic 初始化一个新站点（类似这个）。

配置您的站点​

修改 docusaurus.config.js 以添加对法语语言的 i18n 支持。

站点配置​

使用站点 i18n 配置声明 i18n 语言环境：

docusaurus.config.js
export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'fa'],
    localeConfigs: {
      en: {
        htmlLang: 'en-GB',
      },
      // 如果不需要覆盖默认值，可以省略语言环境（例如 fr）
      fa: {
        direction: 'rtl',
      },
    },
  },
};

语言环境名称用于翻译文件的位置以及翻译语言的基本 URL。构建所有语言环境时，只有默认语言环境的名称在基本 URL 中被省略。

Docusaurus 使用语言环境名称提供明智的默认值：<html lang="..."> 属性、语言环境标签、日历格式等。您可以使用 localeConfigs 自定义这些默认值。

主题配置​

添加一个类型为 localeDropdown 的导航栏项目，以便用户可以选择他们想要的语言环境：

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
        },
      ],
    },
  },
};
提示

您可以传递一个查询参数，当用户使用下拉菜单更改语言环境时，该参数将附加到 URL（例如 queryString: '?persistLocale=true'）。

这对于在服务器上实现自动语言环境检测很有用。例如，您可以使用此参数将用户的首选语言环境存储在 cookie 中。

启动您的站点​

在开发模式下启动本地化站点，使用您选择的语言环境：

npm run start -- --locale fr

您的站点可在 http://localhost:3000/fr/ 访问。

我们尚未提供任何翻译，因此站点大部分是未翻译的。

提示

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

请帮助我们完成这些**默认翻译**。

注意

每个语言环境都是一个独立的单页应用：无法同时启动所有语言环境的 Docusaurus 站点。

翻译您的站点​

法语语言环境的所有翻译数据都存储在 website/i18n/fr 中。每个插件在相应的文件夹下获取其自己的翻译内容，而 code.json 文件定义了 React 代码中使用的所有文本标签。

备注

复制文件后，使用 npm run start -- --locale fr 重新启动您的站点。编辑现有文件时，热重载效果会更好。

翻译您的 React 代码​

对于您自己编写的任何 React 代码：React 页面、React 组件等，您将使用翻译 API。

找出 React 代码中对用户可见的所有文本标签，并使用翻译 API 标记它们。有两种 API：

  • <Translate> 组件将字符串包装为 JSX 元素；
  • translate() 回调接受一条消息并返回一个字符串。

选择更适合上下文语义的那个。例如，<Translate> 可以用作 React 子元素，而对于需要字符串的 props，可以使用回调。

注意

JSX 元素是一个_对象_，而不是字符串。在期望字符串的上下文中使用它（例如 <option> 的子元素）会将其强制转换为字符串，这将返回 "[object Object]"。虽然我们鼓励您在 JSX 子元素中使用 <Translate>，但只有在实际有效时才使用元素形式。

src/pages/index.js
import React from 'react';
import Layout from '@theme/Layout';
import Link from '@docusaurus/Link';

export default function Home() {
  return (
    <Layout>
      <h1>Welcome to my website</h1>
      <main>
        You can also visit my
        <Link to="https://docusaurus.io/blog">blog</Link>
        <img
          src="/img/home.png"
          alt="Home icon"
        />
      </main>
    </Layout>
  );
}

初始化翻译文件​

使用 CLI 命令生成初始翻译文件：

npm run docusaurus write-translations -- --locale fr

这将在 website/i18n/fr 中创建所有必要的翻译文件。

翻译 Markdown 文件​

对于文档、博客和页面，将 Markdown 文件复制到相应的翻译文件夹中：

mkdir -p website/i18n/fr/docusaurus-plugin-content-docs/current
cp website/docs/intro.md website/i18n/fr/docusaurus-plugin-content-docs/current/intro.md

然后编辑 website/i18n/fr/docusaurus-plugin-content-docs/current/intro.md 以提供法语翻译。

对于博客文章：

mkdir -p website/i18n/fr/docusaurus-plugin-content-blog
cp website/blog/2021-08-01-mdx-blog-post.mdx website/i18n/fr/docusaurus-plugin-content-blog/2021-08-01-mdx-blog-post.mdx

翻译 JSON 文件​

编辑 website/i18n/fr/code.json 和其他 JSON 文件（如 navbar.json、footer.json）以提供翻译。

构建和部署​

构建您的本地化站点：

npm run build -- --locale fr

部署时，您可以选择单域名或多域名策略。

高级主题​

翻译工作流程​

有几种翻译工作流程：

  • Git 工作流：在同一仓库中，每个语言环境都有一个分支
  • SaaS 工作流：使用 Crowdin、Transifex 等
  • 手动工作流：直接编辑翻译文件

使用 Crowdin​

Crowdin 是一个流行的翻译管理平台。我们提供了一个 Crowdin 集成。

部署策略​

  • 单域名：https://docusaurus.io/fr/
  • 多域名：https://fr.docusaurus.io/

结论​

Docusaurus 的 i18n 系统旨在简化网站本地化过程。通过遵循本教程，您已经了解了如何为您的站点添加多语言支持。

祝您的网站本地化之旅顺利！