i18n - 简介
优质
小牛编辑
145浏览
2023-12-01
借助 Docusaurus 对国际化(i18n)的支持,可以 轻松地翻译 Docusaurus 网站 。
目标
了解 Docusaurus 对 i18n 支持的背后所做的 设计决策 很重要。
i18n 的目标
Docusaurus 的 i18n 系统的目标是:
- 简单:只需将翻译后的文件放到正确文件系统位置即可使用
- 灵活的翻译流程:支持 Git(单体仓库、分支或子模块)、SaaS 软件、FTP
- 灵活的部署选择:单个或多个域名或混合使用
- 模块化:让插件作者也能提供对 i18n 的支持
- 低开销的运行时:文档大部分是静态的,不需要引入巨大的 JS 库或 polyfills
- 弹性构建:允许独立构建和部署本地化的网站
- 本地化静态资源:网站上的图片可能包含需要翻译的文字
- 无耦合:不强制使用任何 SaaS 软件,但可以提供相应的集成
- 易于结合 Crowdin 使用:许多 Docusaurus v1 网站在使用 Crowdin,应当便于迁移到 Docusaurus v2
- 良好的 SEO 默认设置:我们为你设置了有用的 SEO 标头,例如
hreflang
- 对 RTL 的支持:支持从右往左读的语言(阿拉伯语、希伯来语等),并且易于实现
- 默认翻译:classic 主题中的某些内容以为你翻译成 多种语言 了
非 i18n 的目标
我们不提供以下支持:
- 自动语言检测: 坚持认为最好在 服务器端 实现
- 辅助翻译的 SaaS 软件:了解你所选择使用的外部工具是你自己的责任
- 对链接(slugs)的翻译:技术复杂,SEO 价值低
翻译流程
概述
翻译 Docusaurus 网站的流程大概如下:
- 配置:在
docusaurus.config.js
文件中声明默认语言和其它语言 - 翻译:将待翻译文件放到正确的文件系统位置上
- 部署:使用单个或多个域名策略来构建并部署你的网站
待翻译文件
有 2 种待翻译文件需要你处理。
Markdown 文件
这是 Docusaurus 网站的主要内容。
将 Markdown 和 MDX 文档作为整体进行翻译,而不是将每个句子拆分成单独的字符串进行翻译,以便完全保留翻译的上下文。
JSON 文件
以下内容利用 JSON 格式的文件进行翻译:
- React 代码:使用
<Translate>
组件的内容 - 主题:导航条、页脚
- 插件:文档侧边栏的类别标签
所使用的 JSON 格式被称为 Chrome i18n:
{ "myTranslationKey1": { "message": "Translated message 1", "description": "myTranslationKey1 is used on the homepage" }, "myTranslationKey2": { "message": "Translated message 2", "description": "myTranslationKey2 is used on the FAQ page" } }
做出此选择有两个原因:
- 描述性的属性:为翻译人员提供上下文
- 广泛的支持:Chrome 扩展程序、Crowdin、Transifex、Phrase、Applanga
待翻译文档所在的位置
创建的待翻译文件应当放在正确的文件系统位置上。
每种语言和插件都有其自己的 i18n
子文件夹:
website/i18n/<locale>/<pluginName>/...
note
对于支持多实例的插件,路径是 website/i18n/<locale>/<pluginName>-<pluginId>/...
.
假如将一个非常简单的网站翻译为法语版本,则会具有以下结构树:
website/i18n └── fr ├── code.json │ ├── docusaurus-plugin-content-blog │ └── 2020-01-01-hello.md │ ├── docusaurus-plugin-content-docs │ ├── current # │ │ ├── doc1.md │ │ └── doc2.mdx │ └── current.json │ └── docusaurus-theme-classic ├── footer.json └── navbar.json
JSON 文件是通过 docusaurus write-translations
CLI 命令初始化的。
code.json
文件是利用 <Translate>
API 从 React 组件中提取出来的。
info
注意,docusaurus-plugin-content-docs
插件具有一个 current
子文件夹和一个 current.json
文件,用于 文档版本化功能。
每个插件或主题所具有的文件和文件夹都是不同的,并且 对待翻译文件的位置都有各自的定义: