Skip to main content
国际化（i18n）是将软件或内容设计为适配不同语言和地区设置的过程。本指南将说明如何规划文件结构、配置导航，以及高效维护翻译内容，从而帮助用户以其首选语言访问你的文档，并提升全球触达能力。

​
文件结构

将翻译后的内容组织在各自语言的目录中，以保持文档的可维护性，并按语言来构建导航结构。 使用 ISO 639-1 语言代码 为每种语言分别创建一个单独的目录。将翻译后的文件放入这些目录中，并保持与默认语言相同的结构。
Example file structure
docs/
├── index.mdx                    # English (default)
├── quickstart.mdx
├── fr/
│   ├── index.mdx               # French
│   ├── quickstart.mdx
├── es/
│   ├── index.mdx               # 西班牙文
│   ├── quickstart.mdx
└── zh/
    ├── index.mdx               # Chinese
    └── quickstart.mdx
在所有语言中保持相同的文件名和目录结构，这样更便于维护翻译并发现缺失的内容。

​
配置语言切换器

要在文档中添加语言切换器，请在 docs.json 的 navigation 配置中设置 languages 数组。
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 语言代码
  • 完整的导航结构
  • 指向已翻译文件的路径
不同语言的导航结构可以有所不同，以满足各语言特定的内容需求。
将导航标签（例如分组或标签页名称）翻译为与内容语言一致的文本，可以为用户提供完全本地化的体验。
要添加在所有语言版本中都显示的全局导航元素，请在 docs.json 的 navigation 配置中设置 global 对象。
docs.json
{
  "navigation": {
    "global": {
      "anchors": [
        {
          "anchor": "Documentation",
          "href": "https://example.com/docs"
        },
        {
          "anchor": "Blog",
          "href": "https://example.com/blog"
        }
      ]
    },
    "languages": [
      // 特定语言导航
    ]
  }
}

​
维护翻译

确保译文准确无误，并与源内容保持同步。

​
翻译工作流程

  1. 在主语言中更新源内容。
  2. 确定已更改的内容。
  3. 翻译已更改的内容。
  4. 审核译文的准确性。
  5. 更新翻译文件。
  6. 验证导航和链接是否正常工作。

​
自动化翻译

如需自动化翻译解决方案，请联系 Mintlify 销售团队。

​
图片与媒体

将各语言版本的图片存放在对应的语言目录中。 
images/
├── dashboard.png          # 英文版
├── fr/
│   └── dashboard.png     # 法文版
└── es/
    └── dashboard.png     # 西班牙文版
在译文中使用相对路径引用图像。
es/index.mdx
![控制台截图](/images/es/dashboard.png)

​
多语言网站的 SEO（搜索引擎优化）

针对每种语言版本进行搜索引擎优化。

​
页面元数据

在每个文件的 frontmatter 中包含已翻译的页面元数据：
fr/index.mdx
---
title: "开始使用"
description: "了解如何开始使用我们的产品。"
keywords: ["入门", "教程", "指南"]
---

​
hreflang 标签

Mintlify 会为文档的每种语言版本自动生成 hreflang 标签，帮助搜索引擎理解不同语言版本页面之间的对应关系。

​
最佳实践

​
日期和数字格式

注意针对不同地区使用合适的日期和数字格式。
  • 日期格式：MM/DD/YYYY vs DD/MM/YYYY
  • 数字格式：1,000.00 vs 1.000,00
  • 货币符号：$100.00 vs 100,00€
为每种语言使用相应格式的示例，或采用通用且易于理解的格式。

​
保持一致性

  • 在所有语言中保持内容对齐，确保每位用户获取同等质量的信息。
  • 为技术术语创建翻译术语表。
  • 在不同语言中保持相同的内容结构。
  • 匹配源内容的语气和风格。
  • 使用 Git branch 将翻译工作与主内容更新分开管理。

​
布局差异

有些语言相比英语需要更多或更少的空间。请在不同屏幕尺寸上测试你的翻译内容，以确保：
  • 导航显示正常且不会被截断。
  • 代码块不会溢出。
  • 表格和其他格式化文本保持良好的可读性。
  • 图片能够适当缩放。

​
字符编码

请确保你的开发环境和部署流水线支持 UTF-8 编码，以便正确显示使用不同字母表并包含特殊字符的各种语言中的所有字符。