多语言支持

如果您的文档需要覆盖多个语言的用户，可以为每个区域设置定义独立的导航树，并让读者通过顶部栏中的下拉菜单切换语言。

配置

将导航包装在 languages 数组中，并为每种语言提供独立的导航结构：

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "tabs": [
          {
            "tab": "Documentation",
            "groups": [
              {
                "group": "Getting Started",
                "pages": ["introduction", "quickstart"]
              }
            ]
          }
        ]
      },
      {
        "language": "es",
        "tabs": [
          {
            "tab": "Documentación",
            "groups": [
              {
                "group": "Comenzar",
                "pages": ["es/introduction", "es/quickstart"]
              }
            ]
          }
        ]
      }
    ]
  }
}

支持的语言

目录结构

将翻译后的内容组织到带语言前缀的目录中：

my-docs/
├── docs.json
├── introduction.mdx          # English (default)
├── quickstart.mdx
├── es/
│   ├── introduction.mdx      # Spanish
│   └── quickstart.mdx
├── fr/
│   ├── introduction.mdx      # French
│   └── quickstart.mdx
└── de/
    ├── introduction.mdx      # German
    └── quickstart.mdx

在导航中使用完整路径引用页面（包含语言前缀）：

{
  "language": "es",
  "tabs": [
    {
      "tab": "Documentación",
      "groups": [
        {
          "group": "Comenzar",
          "pages": ["es/introduction", "es/quickstart"]
        }
      ]
    }
  ]
}

特定语言的设置

每种语言都可以拥有自己的配置：

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "tabs": [...]
      },
      {
        "language": "es",
        "tabs": [...]
      }
    ]
  }
}

翻译导航栏标签

顶部导航链接和主要 CTA 接受可选的 labels 对象，用于按语言覆盖标签。当读者访问带语言前缀的 URL（例如 /fr/...）时，将使用匹配的覆盖标签；否则显示默认的 label。

{
  "navbar": {
    "links": [
      {
        "label": "Blog",
        "labels": { "fr": "Blog", "es": "Blog" },
        "href": "/blog"
      },
      {
        "label": "Pricing",
        "labels": { "fr": "Tarifs", "es": "Precios" },
        "href": "/pricing"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "labels": { "fr": "Tableau de bord", "es": "Panel" },
      "href": "https://app.example.com"
    }
  }
}

内置 UI 字符串（Search 按钮、Ask AI 按钮和 More 标签下拉菜单）会自动翻译为每种受支持的语言。您无需配置这些内容。

默认语言

数组中的第一种语言是默认语言。用户访问您的文档时会首先看到这种语言。语言切换器允许用户进行切换。

URL 结构

语言前缀会显示在 URL 中：

部分翻译

您不必翻译每个页面。如果某种语言中不存在某个页面，用户会看到一条回退消息，其中包含指向英文版本的链接。

对于不应翻译的页面（例如 API 参考），您可以让不同语言引用同一个页面：

{
  "language": "es",
  "tabs": [
    {
      "tab": "API",
      "groups": [
        {
          "group": "Endpoints",
          "pages": ["api/users", "api/posts"]  // Same as English
        }
      ]
    }
  ]
}

翻译 OpenAPI 规范

由 OpenAPI 驱动的端点页面（包含 openapi: frontmatter 指令的页面）会从 YAML 或 JSON 规范文件中渲染内容。要翻译端点摘要、描述、参数提示和架构字段描述，请在英文规范文件旁提供特定语言的规范文件。

文件命名

将翻译后的规范放在源文件旁边，并在扩展名前插入语言代码：

openapi/
├── api.yaml           # English (default)
├── api.fr.yaml        # French
├── api.es.yaml        # Spanish
└── api.zh.yaml        # Simplified Chinese

无需修改配置或 docs.json。Jamdesk 会根据 URL 的语言前缀，在渲染时解析匹配的规范。对于 /fr/api-reference/create-ticket 页面，Jamdesk 会优先查找 api.fr.yaml；如果不存在翻译，则回退到 api.yaml。

规范中需要翻译的内容

翻译可读文本。不同语言之间的所有结构性值都必须保持一致。

回退行为

如果在本地化 URL 下请求页面，但不存在翻译后的规范，Jamdesk 会在翻译后的页面外壳中渲染英文规范。用户会看到混合语言的端点区块，而不是 404。这与 MDX 页面的部分翻译行为一致。

删除特定语言的规范

删除 api.<lang>.yaml 后，页面会在下一次渲染时回退到英文规范（无需重新构建）。要从头开始重新翻译，请删除该文件并重新生成。无需修改 docs.json——规范解析完全基于文件名。

示例

源文件 openapi/tickets.yaml：

info:
  title: Tickets API
  description: Manage support tickets.
paths:
  /tickets:
    post:
      summary: Create a ticket
      description: Create a new support ticket.
      operationId: createTicket

法语翻译文件 openapi/tickets.fr.yaml：

info:
  title: API Tickets
  description: Gérez les tickets de support.
paths:
  /tickets:
    post:
      summary: Créer un ticket
      description: Créer un nouveau ticket de support.
      operationId: createTicket

请注意，/tickets、post 和 createTicket 保持不变。只有文本内容发生变化。

翻译工作流

RTL 语言

支持阿拉伯语和希伯来语等从右到左的语言。启用这些语言后，Jamdesk 会自动应用 RTL 样式。

接下来做什么？