mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
97dd998f47
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
424 lines
11 KiB
Plaintext
424 lines
11 KiB
Plaintext
---
|
||
title: "国际化"
|
||
description: "设置多语言文档，以触达全球用户。"
|
||
keywords: ["国际化", "i18n", "多语言", "翻译", "本地化", "语言切换器"]
|
||
---
|
||
|
||
国际化（i18n）是将软件或内容设计为适配不同语言和地区设置的过程。本指南将说明如何规划文件结构、配置导航，以及高效维护翻译内容，从而帮助用户以其首选语言访问你的文档，并提升全球触达能力。
|
||
|
||
<div id="file-structure">
|
||
## 文件结构
|
||
</div>
|
||
|
||
将翻译后的内容组织在各自语言的目录中，以保持文档的可维护性，并按语言来构建导航结构。
|
||
|
||
使用 [ISO 639-1 语言代码](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 为每种语言分别创建一个单独的目录。将翻译后的文件放入这些目录中，并保持与默认语言相同的结构。
|
||
|
||
<Expandable title="支持的语言代码">
|
||
* `ar` - 阿拉伯语
|
||
* `cs` - 捷克语
|
||
* `zh` or `zh-Hans` - 中文 (简体)
|
||
* `zh-Hant` - 中文 (繁体)
|
||
* `de` - 德语
|
||
* `en` - 英语
|
||
* `es` - 西班牙语
|
||
* `fr` - 法语
|
||
* `he` - 希伯来语
|
||
* `hi` - 印地语
|
||
* `id` - 印度尼西亚语
|
||
* `it` - 意大利语
|
||
* `jp` - 日语
|
||
* `ko` - 韩语
|
||
* `lv` - 拉脱维亚语
|
||
* `nl` - 荷兰语
|
||
* `no` - 挪威语
|
||
* `pl` - 波兰语
|
||
* `pt` or `pt-BR` - 葡萄牙语
|
||
* `ro` - 罗马尼亚语
|
||
* `ru` - 俄语
|
||
* `sv` - 瑞典语
|
||
* `tr` - 土耳其语
|
||
* `ua` - 乌克兰语
|
||
* `uz` - 乌兹别克语
|
||
* `vi` - 越南语
|
||
</Expandable>
|
||
|
||
```text Example file structure
|
||
docs/
|
||
├── index.mdx # English (default)
|
||
├── quickstart.mdx
|
||
├── fr/
|
||
│ ├── index.mdx # French
|
||
│ ├── quickstart.mdx
|
||
├── es/
|
||
│ ├── index.mdx # Spanish
|
||
│ ├── quickstart.mdx
|
||
└── zh/
|
||
├── index.mdx # Chinese
|
||
└── quickstart.mdx
|
||
```
|
||
|
||
<Tip>
|
||
在所有语言中保持相同的文件名和目录结构，这样更便于维护翻译并发现缺失的内容。
|
||
</Tip>
|
||
|
||
|
||
<div id="configure-the-language-switcher">
|
||
## 配置语言切换器
|
||
</div>
|
||
|
||
要在文档中添加语言切换器，请在 `docs.json` 的 `navigation` 配置中设置 `languages` 数组。
|
||
|
||
```json docs.json
|
||
{
|
||
"navigation": {
|
||
"languages": [
|
||
{
|
||
"language": "en",
|
||
"groups": [
|
||
{
|
||
"group": "快速入门",
|
||
"pages": ["index", "quickstart"]
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"language": "es",
|
||
"groups": [
|
||
{
|
||
"group": "Comenzando",
|
||
"pages": ["es/index", "es/quickstart"]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
`languages` 数组中的每个语言条目都需要：
|
||
|
||
* `language`：ISO 639-1 语言代码
|
||
* 完整的导航结构
|
||
* 指向已翻译文件的路径
|
||
|
||
不同语言的导航结构可以有所不同，以满足各语言特定的内容需求。
|
||
|
||
|
||
<div id="set-default-language">
|
||
### 设置默认语言
|
||
</div>
|
||
|
||
`languages` 数组中的第一个语言会自动作为默认语言。若要使用其他语言作为默认语言，可以重新调整数组顺序，或添加 `default` 属性：
|
||
|
||
```json docs.json
|
||
{
|
||
"navigation": {
|
||
"languages": [
|
||
{
|
||
"language": "es",
|
||
"groups": [...]
|
||
},
|
||
{
|
||
"language": "en",
|
||
"groups": [...]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
或者使用 `default` 属性来指定顺序：
|
||
|
||
```json docs.json
|
||
{
|
||
"navigation": {
|
||
"languages": [
|
||
{
|
||
"language": "en",
|
||
"groups": [...]
|
||
},
|
||
{
|
||
"language": "es",
|
||
"default": true,
|
||
"groups": [...]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
<div id="single-language-documentation">
|
||
### 单语言文档
|
||
</div>
|
||
|
||
如果你只想提供一种语言并且不需要语言切换器，请从 navigation 配置中移除 `languages` 字段，而是直接定义导航结构：
|
||
|
||
```json docs.json
|
||
{
|
||
"navigation": {
|
||
"tabs": [
|
||
{
|
||
"tab": "Documentation",
|
||
"groups": [
|
||
{
|
||
"group": "Getting started",
|
||
"pages": ["index", "quickstart"]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
这会以单一语言显示你的文档，并且不提供语言切换器界面。
|
||
|
||
<Tip>
|
||
将导航标签（例如分组或标签页名称）翻译为与内容语言一致的文本，可以为用户提供完全本地化的体验。
|
||
</Tip>
|
||
|
||
|
||
<div id="global-navigation">
|
||
### 全局导航
|
||
</div>
|
||
|
||
要添加在所有语言版本中都显示的全局导航元素，请在 `docs.json` 的 `navigation` 配置中设置 `global` 对象。
|
||
|
||
```json docs.json
|
||
{
|
||
"navigation": {
|
||
"global": {
|
||
"anchors": [
|
||
{
|
||
"anchor": "Documentation",
|
||
"href": "https://example.com/docs"
|
||
},
|
||
{
|
||
"anchor": "Blog",
|
||
"href": "https://example.com/blog"
|
||
}
|
||
]
|
||
},
|
||
"languages": [
|
||
// 特定语言导航
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
<div id="maintain-translations">
|
||
## 维护翻译
|
||
</div>
|
||
|
||
确保译文准确无误，并与源内容保持同步。
|
||
|
||
<div id="translation-workflow">
|
||
### 翻译工作流程
|
||
</div>
|
||
|
||
1. 在主语言中更新源内容。
|
||
2. 确定已更改的内容。
|
||
3. 翻译已更改的内容。
|
||
4. 审核译文的准确性。
|
||
5. 更新翻译文件。
|
||
6. 验证导航和链接是否正常工作。
|
||
|
||
<div id="automated-translations">
|
||
### 自动化翻译
|
||
</div>
|
||
|
||
如需自动化翻译解决方案，请[联系 Mintlify 销售团队](mailto:gtm@mintlify.com)。
|
||
|
||
<div id="external-translation-providers">
|
||
### 外部翻译服务商
|
||
</div>
|
||
|
||
如果你与自己的翻译供应商或区域译员合作，可以使用 GitHub Actions 或类似的 CI/CD 工具，将他们的工作流程集成到 Mintlify 文档中。
|
||
|
||
1. **导出源内容**：提取需要翻译的 MDX 文件。
|
||
2. **发送给译员**：将文件提供给翻译服务商。
|
||
3. **接收译文**：取回翻译后的 MDX 文件。
|
||
4. **导入并部署**：将翻译后的文件添加到语言目录中，并更新导航。
|
||
|
||
当 PR 合并到 main 时，此 GitHub Actions 工作流程会自动导出已更改的英文内容以供翻译。
|
||
|
||
```yaml .github/workflows/export-for-translation.yml
|
||
name: Export content for translation
|
||
|
||
on:
|
||
push:
|
||
branches: [main]
|
||
paths:
|
||
- '*.mdx'
|
||
- '!es/**'
|
||
- '!fr/**'
|
||
- '!zh/**'
|
||
|
||
jobs:
|
||
export:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
with:
|
||
fetch-depth: 2
|
||
|
||
- name: Get changed files
|
||
id: changed
|
||
run: |
|
||
echo "files=$(git diff --name-only HEAD~1 HEAD -- '*.mdx' ':!es/' ':!fr/' ':!zh/' | tr '\n' ' ')" >> $GITHUB_OUTPUT
|
||
|
||
- name: Create translation package
|
||
if: steps.changed.outputs.files != ''
|
||
run: |
|
||
for file in ${{ steps.changed.outputs.files }}; do
|
||
mkdir -p "translation-export/$(dirname "$file")"
|
||
cp "$file" "translation-export/$file"
|
||
done
|
||
|
||
- name: Upload translation package
|
||
if: steps.changed.outputs.files != ''
|
||
uses: actions/upload-artifact@v4
|
||
with:
|
||
name: translation-export-${{ github.sha }}
|
||
path: translation-export/
|
||
```
|
||
|
||
该 GitHub Actions 工作流会在通过 PR 添加翻译内容时进行验证并导入。
|
||
|
||
```yaml .github/workflows/import-translations.yml
|
||
name: Import translations
|
||
|
||
on:
|
||
pull_request:
|
||
paths:
|
||
- 'es/**'
|
||
- 'fr/**'
|
||
- 'zh/**'
|
||
|
||
jobs:
|
||
validate:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: Validate frontmatter
|
||
run: |
|
||
for file in $(git diff --name-only origin/main...HEAD -- '*.mdx'); do
|
||
if ! head -1 "$file" | grep -q '^---$'; then
|
||
echo "错误：$file 缺少 frontmatter"
|
||
exit 1
|
||
fi
|
||
done
|
||
|
||
- name: Check file structure
|
||
run: |
|
||
# 验证已翻译文件与源文件结构匹配
|
||
for lang in es fr zh; do
|
||
if [ -d "$lang" ]; then
|
||
for file in $(find "$lang" -name '*.mdx'); do
|
||
source_file="${file#*/}"
|
||
if [ ! -f "$source_file" ]; then
|
||
echo "Warning：$file 在 $source_file 处没有对应的英文源文件"
|
||
fi
|
||
done
|
||
fi
|
||
done
|
||
```
|
||
|
||
**外部翻译工作流最佳实践**
|
||
|
||
* **保留 frontmatter**：确保译员保持 YAML frontmatter 完整，仅翻译 `title` 和 `description` 的值。
|
||
* **保护代码块**：将代码块标记为“请勿翻译”，并告知翻译供应商。
|
||
* **使用翻译记忆库**：提供术语表，列出应保留英文或需采用特定译法的技术术语。
|
||
* **自动化验证**：在合并翻译内容前，使用 CI 检查验证 MDX 语法和 frontmatter。
|
||
* **版本控制**：跟踪每份译文对应的源版本，以识别过时内容。
|
||
|
||
|
||
<div id="images-and-media">
|
||
### 图片与媒体
|
||
</div>
|
||
|
||
将各语言版本的图片存放在对应的语言目录中。
|
||
|
||
```
|
||
images/
|
||
├── dashboard.png # 英文版
|
||
├── fr/
|
||
│ └── dashboard.png # 法文版
|
||
└── es/
|
||
└── dashboard.png # 西班牙文版
|
||
```
|
||
|
||
在译文中使用相对路径引用图像。
|
||
|
||
```mdx es/index.mdx
|
||
|
||
```
|
||
|
||
|
||
<div id="seo-for-multi-language-sites">
|
||
## 多语言网站的 SEO（搜索引擎优化）
|
||
</div>
|
||
|
||
针对每种语言版本进行搜索引擎优化。
|
||
|
||
<div id="page-metadata">
|
||
### 页面元数据
|
||
</div>
|
||
|
||
在每个文件的 frontmatter 中包含已翻译的页面元数据：
|
||
|
||
```mdx fr/index.mdx
|
||
---
|
||
title: "开始使用"
|
||
description: "了解如何开始使用我们的产品。"
|
||
keywords: ["入门", "教程", "指南"]
|
||
---
|
||
```
|
||
|
||
|
||
<div id="best-practices">
|
||
## 最佳实践
|
||
</div>
|
||
|
||
<div id="date-and-number-formats">
|
||
### 日期和数字格式
|
||
</div>
|
||
|
||
注意针对不同地区使用合适的日期和数字格式。
|
||
|
||
- 日期格式：MM/DD/YYYY vs DD/MM/YYYY
|
||
- 数字格式：1,000.00 vs 1.000,00
|
||
- 货币符号：$100.00 vs 100,00€
|
||
|
||
为每种语言使用相应格式的示例，或采用通用且易于理解的格式。
|
||
|
||
<div id="maintain-consistency">
|
||
### 保持一致性
|
||
</div>
|
||
|
||
- 在所有语言中保持内容对齐，确保每位用户获取同等质量的信息。
|
||
- 为技术术语创建翻译术语表。
|
||
- 在不同语言中保持相同的内容结构。
|
||
- 匹配源内容的语气和风格。
|
||
- 使用 Git branch 将翻译工作与主内容更新分开管理。
|
||
|
||
<div id="layout-differences">
|
||
### 布局差异
|
||
</div>
|
||
|
||
有些语言相比英语需要更多或更少的空间。请在不同屏幕尺寸上测试你的翻译内容，以确保：
|
||
|
||
- 导航显示正常且不会被截断。
|
||
- 代码块不会溢出。
|
||
- 表格和其他格式化文本保持良好的可读性。
|
||
- 图片能够适当缩放。
|
||
|
||
<div id="character-encoding">
|
||
### 字符编码
|
||
</div>
|
||
|
||
请确保你的开发环境和部署流水线支持 UTF-8 编码，以便正确显示使用不同字母表并包含特殊字符的各种语言中的所有字符。 |