国际化 (i18n)

国际化使您的文档能够被全球受众访问。Rspress 提供全面的 i18n 支持,使创建多语言文档网站变得容易。

理解 i18n

什么是 i18n?

国际化(i18n)是设计软件以支持多种语言和地区而无需工程更改的过程。

关键概念:

语言环境: 语言和地区组合(en-US, zh-CN, ja-JP)
翻译: 将内容从一种语言转换为另一种语言
本地化 (l10n): 为特定地区调整内容
默认语言环境: 您网站的后备语言

为什么要国际化?

更广泛的受众: 触及非英语用户
更好的用户体验: 用户更喜欢母语内容
提高参与度: 本地化内容的参与度更高
SEO 优势: 在不同地区的搜索排名更好

基本 i18n 设置

配置

在 rspress.config.ts 中配置语言环境:

// rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  locales: [
    {
      lang: 'en',
      label: 'English',
      title: 'My Documentation',
      description: 'Documentation site',
    },
    {
      lang: 'zh',
      label: '简体中文',
      title: '我的文档',
      description: '文档网站',
    },
    {
      lang: 'ja',
      label: '日本語',
      title: '私のドキュメント',
      description: 'ドキュメントサイト',
    },
  ],
});

目录结构

按语言环境组织内容:

docs/
├── en/                    # 英文内容
│   ├── index.md
│   ├── guide/
│   │   ├── getting-started.md
│   │   └── configuration.md
│   └── api/
│       └── reference.md
├── zh/                    # 中文内容
│   ├── index.md
│   ├── guide/
│   │   ├── getting-started.md
│   │   └── configuration.md
│   └── api/
│       └── reference.md
└── ja/                    # 日文内容
    ├── index.md
    └── guide/
        └── getting-started.md

默认语言环境

设置默认语言环境:

export default defineConfig({
  defaultLocale: 'en',  // 默认语言
  locales: [
    {
      lang: 'en',
      label: 'English',
    },
    {
      lang: 'zh',
      label: '简体中文',
    },
  ],
});

语言切换

自动语言选择器

Rspress 自动在导航栏添加语言选择器:

// 不需要额外配置!
// 当配置多个语言环境时,语言选择器自动出现

语言检测

Rspress 可以检测用户的首选语言:

export default defineConfig({
  locales: [...],
  // 根据浏览器语言自动重定向
  // 用户仍然可以手动切换语言
});

翻译内容

页面翻译

为每种语言创建相应的文件:

<!-- docs/en/guide/getting-started.md -->
---
title: Getting Started
description: Learn how to get started
---

# Getting Started

Welcome to our documentation!

## Installation

Run the following command:

<!-- docs/zh/guide/getting-started.md -->
---
title: 快速开始
description: 学习如何开始使用
---

# 快速开始

欢迎使用我们的文档!

## 安装

运行以下命令:

维护 URL 结构

在语言之间保持 URL 一致:

英文:  /en/guide/getting-started
中文:  /zh/guide/getting-started
日文:  /ja/guide/getting-started

Frontmatter 翻译

翻译 frontmatter 元数据:

<!-- 英文 -->
---
title: Advanced Configuration
description: Learn advanced configuration options
keywords: [config, advanced, setup]
---

<!-- 中文 -->
---
title: 高级配置
description: 学习高级配置选项
keywords: [配置, 高级, 设置]
---

导航翻译

每种语言的导航

为每种语言配置不同的导航:

export default defineConfig({
  locales: [
    {
      lang: 'en',
      label: 'English',
      themeConfig: {
        nav: [
          { text: 'Home', link: '/en/' },
          { text: 'Guide', link: '/en/guide/' },
          { text: 'API', link: '/en/api/' },
        ],
        sidebar: {
          '/en/guide/': [
            { text: 'Getting Started', link: '/en/guide/getting-started' },
            { text: 'Configuration', link: '/en/guide/configuration' },
          ],
        },
      },
    },
    {
      lang: 'zh',
      label: '简体中文',
      themeConfig: {
        nav: [
          { text: '首页', link: '/zh/' },
          { text: '指南', link: '/zh/guide/' },
          { text: 'API', link: '/zh/api/' },
        ],
        sidebar: {
          '/zh/guide/': [
            { text: '快速开始', link: '/zh/guide/getting-started' },
            { text: '配置', link: '/zh/guide/configuration' },
          ],
        },
      },
    },
  ],
});

UI 文本翻译

主题文本

翻译内置 UI 文本:

export default defineConfig({
  locales: [
    {
      lang: 'en',
      themeConfig: {
        // 自定义 UI 文本
        searchPlaceholder: 'Search documentation',
        lastUpdated: 'Last Updated',
        editLink: 'Edit this page',
      },
    },
    {
      lang: 'zh',
      themeConfig: {
        searchPlaceholder: '搜索文档',
        lastUpdated: '最后更新',
        editLink: '编辑本页',
      },
    },
  ],
});

自定义 UI 文本

定义自定义翻译:

// locales/en.ts
export const en = {
  common: {
    readMore: 'Read More',
    download: 'Download',
    share: 'Share',
  },
  guide: {
    next: 'Next Step',
    previous: 'Previous',
  },
};

// locales/zh.ts
export const zh = {
  common: {
    readMore: '阅读更多',
    download: '下载',
    share: '分享',
  },
  guide: {
    next: '下一步',
    previous: '上一步',
  },
};

在组件中使用:

import { useI18n } from 'rspress/runtime';
import { en } from './locales/en';
import { zh } from './locales/zh';

const translations = { en, zh };

export function CustomComponent() {
  const { lang } = useI18n();
  const t = translations[lang] || translations.en;

  return (
    <button>{t.common.readMore}</button>
  );
}

特定语言功能

日期格式化

按语言环境格式化日期:

import { useI18n } from 'rspress/runtime';

export function DateDisplay({ date }: { date: Date }) {
  const { lang } = useI18n();

  const formatted = new Intl.DateTimeFormat(lang, {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  }).format(date);

  return <time>{formatted}</time>;
}

数字格式化

export function NumberDisplay({ value }: { value: number }) {
  const { lang } = useI18n();

  const formatted = new Intl.NumberFormat(lang).format(value);

  return <span>{formatted}</span>;
}

RTL 支持

从右到左语言

支持 RTL 语言(阿拉伯语、希伯来语):

export default defineConfig({
  locales: [
    {
      lang: 'en',
      label: 'English',
    },
    {
      lang: 'ar',
      label: 'العربية',
      dir: 'rtl',  // 启用 RTL
    },
  ],
});

多语言网站的 SEO

HTML Lang 属性

Rspress 自动设置 lang 属性:

<!-- 英文页面 -->
<html lang="en">

<!-- 中文页面 -->
<html lang="zh">

hreflang 标签

添加备用语言链接:

export default defineConfig({
  head: [
    ['link', { rel: 'alternate', hreflang: 'en', href: 'https://example.com/en/' }],
    ['link', { rel: 'alternate', hreflang: 'zh', href: 'https://example.com/zh/' }],
    ['link', { rel: 'alternate', hreflang: 'x-default', href: 'https://example.com/en/' }],
  ],
});

翻译工作流

翻译过程

编写原始内容(通常是英文)
准备翻译
- 提取可翻译文本
- 为译者注明上下文
翻译内容
- 专业译者
- 社区贡献
- 机器翻译 + 审校
审校与质量保证
- 母语者审校
- 检查格式
- 验证链接
部署

部分翻译

后备到默认语言

当翻译缺失时显示默认语言环境:

export default defineConfig({
  locales: [
    {
      lang: 'en',
      label: 'English',
    },
    {
      lang: 'zh',
      label: '简体中文',
      fallback: 'en',  // 如果中文不可用则使用英文
    },
  ],
});

最佳实践

内容组织

保持结构相同

✅ 好的:
docs/en/guide/getting-started.md
docs/zh/guide/getting-started.md

❌ 不好的:
docs/en/guide/start.md
docs/zh/guide/getting-started.md

使用一致的 URL

✅ 好的: /en/guide/api vs /zh/guide/api
❌ 不好的: /en/guide/api vs /zh/zhinan/api

翻译质量

专业翻译: 尽可能使用专业译者
母语审校: 让母语者审校翻译
上下文: 为译者提供上下文
一致性: 使用术语表保持术语一致

测试

测试所有语言:

# 测试每种语言环境
npm run dev -- --locale en
npm run dev -- --locale zh

# 构建所有语言环境
npm run build

# 测试语言切换
npm run preview

故障排除

缺少翻译

检查文件路径: 确保文件存在于语言环境目录中
验证配置: 检查语言环境配置
检查后备: 确保配置了后备

编码问题

// 确保 UTF-8 编码
export default defineConfig({
  head: [
    ['meta', { charset: 'utf-8' }],
  ],
});

下一步

学习使用多语言的部署
探索静态资源本地化
了解 i18n 网站的SSG/SSR

::: tip 翻译技巧

从高流量页面开始
对关键内容使用专业译者
维护术语表以保持一致性
与母语者一起测试
保持翻译同步 :::

::: warning 常见错误

不要在没有审校的情况下使用机器翻译
不要忘记翻译导航
不要在组件中硬编码文本
不要在 URL 中混合语言 :::

::: info 资源

#国际化 (i18n)

#理解 i18n

#什么是 i18n?

#为什么要国际化?

#基本 i18n 设置

#配置

#目录结构

#默认语言环境

#语言切换

#自动语言选择器

#语言检测

#翻译内容

#页面翻译

#维护 URL 结构

#Frontmatter 翻译

#导航翻译

#每种语言的导航

#UI 文本翻译

#主题文本

#自定义 UI 文本

#特定语言功能

#日期格式化

#数字格式化

#RTL 支持

#从右到左语言

#多语言网站的 SEO

#HTML Lang 属性

#hreflang 标签

#翻译工作流

#翻译过程

#部分翻译

#后备到默认语言

#最佳实践

#内容组织

#翻译质量

#测试

#故障排除

#缺少翻译

#编码问题

#下一步