国际化 (i18n)

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

理解 i18n

什么是 i18n?

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

关键概念:

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

为什么要国际化?

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

基本 i18n 设置

配置

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

typescript

// 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

默认语言环境

设置默认语言环境:

typescript

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

语言切换

自动语言选择器

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

typescript

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

语言检测

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

typescript

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

翻译内容

页面翻译

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

markdown

<!-- 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:

markdown

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

# 快速开始

欢迎使用我们的文档!

## 安装

运行以下命令:

维护 URL 结构

在语言之间保持 URL 一致:

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

Frontmatter 翻译

翻译 frontmatter 元数据:

markdown

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

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

导航翻译

每种语言的导航

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

typescript

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 文本:

typescript

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 文本

定义自定义翻译:

typescript

// 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: '上一步',
  },
};

在组件中使用:

tsx

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>
  );
}

特定语言功能

日期格式化

按语言环境格式化日期:

tsx

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>;
}

数字格式化

tsx

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

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

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

RTL 支持

从右到左语言

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

typescript

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

多语言网站的 SEO

HTML Lang 属性

Rspress 自动设置 lang 属性:

html

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

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

hreflang 标签

添加备用语言链接:

typescript

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/' }],
  ],
});

翻译工作流

翻译过程

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

部分翻译

后备到默认语言

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

typescript

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

翻译质量

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

测试

测试所有语言:

bash

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

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

# 测试语言切换
npm run preview

故障排除

缺少翻译

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

编码问题

typescript

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

下一步

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

翻译技巧

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

常见错误

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

资源

国际化 (i18n) ​

理解 i18n ​

什么是 i18n? ​

为什么要国际化? ​

基本 i18n 设置 ​

配置 ​

目录结构 ​

默认语言环境 ​

语言切换 ​

自动语言选择器 ​

语言检测 ​

翻译内容 ​

页面翻译 ​

维护 URL 结构 ​

Frontmatter 翻译 ​

导航翻译 ​

每种语言的导航 ​

UI 文本翻译 ​

主题文本 ​

自定义 UI 文本 ​

特定语言功能 ​

日期格式化 ​

数字格式化 ​

RTL 支持 ​

从右到左语言 ​

多语言网站的 SEO ​

HTML Lang 属性 ​

hreflang 标签 ​

翻译工作流 ​

翻译过程 ​

部分翻译 ​

后备到默认语言 ​

最佳实践 ​

内容组织 ​

翻译质量 ​

测试 ​

故障排除 ​

缺少翻译 ​

编码问题 ​

下一步 ​

国际化 (i18n)

理解 i18n

什么是 i18n?

为什么要国际化?

基本 i18n 设置

配置

目录结构

默认语言环境

语言切换

自动语言选择器

语言检测

翻译内容

页面翻译

维护 URL 结构

Frontmatter 翻译

导航翻译

每种语言的导航

UI 文本翻译

主题文本

自定义 UI 文本

特定语言功能

日期格式化

数字格式化

RTL 支持

从右到左语言

多语言网站的 SEO

HTML Lang 属性

hreflang 标签

翻译工作流

翻译过程

部分翻译

后备到默认语言

最佳实践

内容组织

翻译质量

测试

故障排除

缺少翻译

编码问题

下一步