Rust国际化插件mdbook-i18n-helpers的使用，为mdbook文档提供多语言翻译和本地化支持

Rust国际化插件mdbook-i18n-helpers的使用，为mdbook文档提供多语言翻译和本地化支持

安装

运行以下命令安装插件：

cargo install mdbook-i18n-helpers

配置

可以在book.toml文件中自定义插件配置：

mdbook-xgettext配置项

  • output.xgettext.pot-file（必填）：设置POT文件路径，典型值是messages.pot
  • output.xgettext.granularity（默认值：1）：设置行号舍入粒度，设为0可完全移除PO文件中的行号

完整使用示例

  1. 首先安装插件：
cargo install mdbook-i18n-helpers
  1. 在mdbook项目中创建book.toml配置文件：
[book]
title = "多语言文档示例"
authors = ["作者名"]

[output.xgettext]
pot-file = "messages.pot"  # 指定POT文件路径
granularity = 1           # 行号舍入粒度
  1. 提取可翻译文本：
mdbook build
mdbook-xgettext
  1. 创建翻译文件（例如中文翻译）：
msginit -i messages.pot -o zh_CN.po -l zh_CN
  1. 编辑翻译文件zh_CN.po：
msgid "Hello, World!"
msgstr "你好，世界！"
  1. 生成翻译后的文档：
mdbook-gettext -p zh_CN.po
mdbook build

功能说明

这些插件使得将用mdbook编写的文档翻译成多种语言变得容易。翻译支持是mdbook长期以来的功能需求。

插件包含三个主要工具：

  • mdbook-xgettext：从markdown文件中提取可翻译文本
  • mdbook-gettext：将翻译应用到文档
  • mdbook-i18n-normalize：规范化翻译文件

注意事项

  1. 这是一个非官方支持的Google产品
  2. 如需帮助，可以联系Martin Geisler或在GitHub上发起讨论

完整示例demo

以下是一个完整的mdbook多语言文档项目示例：

  1. 创建项目目录结构：
my-book/
├── book.toml
├── src/
│   ├── SUMMARY.md
│   └── chapter_1.md
  1. book.toml 配置文件内容：
[book]
title = "Rust多语言文档"
authors = ["Rust开发者"]

[output.xgettext]
pot-file = "messages.pot"
granularity = 1
  1. src/SUMMARY.md 内容：

目录


4. `src/chapter_1.md` 内容：

# 第一章

欢迎阅读Rust文档！

这里有一些需要翻译的内容：
- Rust是一种系统编程语言
- 它注重安全性和性能
  1. 提取翻译文本：
mdbook build
mdbook-xgettext
  1. 创建中文翻译文件：
msginit -i messages.pot -o zh_CN.po -l zh_CN
  1. 编辑zh_CN.po文件：
msgid "Welcome to Rust documentation!"
msgstr "欢迎阅读Rust文档！"

msgid "Rust is a systems programming language"
msgstr "Rust是一种系统编程语言"

msgid "It focuses on safety and performance"
msgstr "它注重安全性和性能"
  1. 生成中文文档：
mdbook-gettext -p zh_CN.po
mdbook build

最终会在book目录下生成翻译后的中文HTML文档。


1 回复

mdbook-i18n-helpers: 为mdbook文档提供多语言支持

介绍

mdbook-i18n-helpers 是一个 Rust 开发的 mdBook 插件，用于为技术文档添加多语言翻译和本地化支持。它可以帮助开发者轻松管理多语言版本的文档，自动化部分翻译流程，并保持文档结构的一致性。

主要功能

  1. 提取可翻译文本到单独的文件
  2. 管理多语言翻译版本
  3. 提供翻译辅助工具
  4. 保持文档结构同步
  5. 自动化部分翻译流程

安装方法

首先确保已安装 mdBook：

cargo install mdbook

然后安装 mdbook-i18n-helpers：

cargo install mdbook-i18n-helpers

基本使用方法

1. 初始化多语言支持

在项目目录下运行：

mdbook i18n init

这会创建基本的目录结构和配置文件。

2. 配置文件

在 book.toml 中添加：

[preprocessor.i18n]
# 启用插件
enabled = true

# 配置支持的语言
[book.languages]
en = "English"
zh = "中文"
es = "Español"

3. 提取可翻译文本

mdbook i18n extract

这会提取所有需要翻译的文本到 po 文件中。

4. 翻译文档

翻译提取出来的 .po 文件，或使用翻译工具处理它们。

5. 构建多语言文档

mdbook build

构建后会在 book 目录下生成每种语言的版本。

示例项目结构

.
├── book.toml
├── src
│   ├── en
│   │   └── summary.md
│   ├── zh
│   │   └── summary.md
│   └── es
│       └── summary.md
├── po
│   ├── en.po
│   ├── zh.po
│   └── es.po
└── theme

高级用法

使用翻译记忆

mdbook i18n update --merge

这会更新翻译文件并保留已有的翻译。

自动化翻译

可以与翻译API集成：

mdbook i18n translate --api deepl --key YOUR_API_KEY

自定义提取规则

在 book.toml 中配置：

[preprocessor.i18n.patterns]
# 忽略某些文件的翻译
ignore = ["CHANGELOG.md"]

注意事项

  1. 保持原始文档和翻译文档的结构一致
  2. 定期运行 mdbook i18n update 同步新增内容
  3. 考虑使用版本控制系统管理翻译文件
  4. 对于技术术语，建议建立术语表保持一致性

替代方案

如果只需要简单的多语言支持，也可以考虑：

  • 使用 mdBook 的原生多语言功能
  • 为每种语言维护单独的 mdBook 项目

但 mdbook-i18n-helpers 提供了更专业的翻译工作流和更好的维护性。

通过这个插件，技术文档团队可以更高效地管理和维护多语言版本的文档，确保全球用户都能获得良好的文档体验。

完整示例demo

以下是一个完整的mdbook多语言项目示例：

  1. 首先创建项目目录并初始化：
# 创建项目目录
mkdir my-i18n-book && cd my-i18n-book

# 初始化mdbook项目
mdbook init

# 初始化i18n支持
mdbook i18n init
  1. 配置book.toml文件：
[book]
title = "多语言文档示例"
authors = ["文档团队"]

[preprocessor.i18n]
enabled = true

[book.languages]
en = "English"
zh = "中文"
ja = "日本語"
  1. 项目结构示例：
my-i18n-book/
├── book.toml
├── src/
│   ├── en/
│   │   ├── summary.md
│   │   └── chapter1.md
│   ├── zh/
│   │   ├── summary.md
│   │   └── chapter1.md
│   └── ja/
│       ├── summary.md
│       └── chapter1.md
├── po/
│   ├── en.po
│   ├── zh.po
│   └── ja.po
└── theme/
  1. 提取翻译文本：
mdbook i18n extract
  1. 翻译po文件示例 (zh.po):
#: src/en/chapter1.md:1
msgid "Getting Started"
msgstr "入门指南"

#: src/en/chapter1.md:3
msgid "This is the first chapter."
msgstr "这是第一章内容。"
  1. 构建多语言文档：
mdbook build
  1. 运行本地服务器查看效果：
mdbook serve --open

这个完整示例展示了如何使用mdbook-i18n-helpers创建和管理一个多语言文档项目，包括初始化、配置、提取翻译、翻译内容和最终构建的完整流程。

回到顶部