如何本地化 OpenAPI 规范

OpenAPI 规范是现代 API 文档的基础。将它们本地化为多种语言有助于全球开发者理解并集成您的 API。但翻译 OpenAPI 规范并不简单——您需要在本地化人类可读内容的同时保持结构。

什么是 OpenAPI？

OpenAPI（前身为 Swagger）是一种描述 REST API 的标准格式。它包括端点、请求/响应模式、参数、身份验证方法和详细描述。这些规范为 Swagger UI、Redoc、Scalar 和代码生成器等工具提供支持——使其对开发者体验至关重要。

翻译挑战

OpenAPI 规范是复杂的 JSON 或 YAML 文件，具有精确的结构。简单的机器翻译工具会破坏它们，因为它们无法理解什么该翻译，什么不该翻译。

智能检测和验证

l10n.dev 自动检测 OpenAPI 规范，并以特殊方式处理它们：

• 自动检测： 该服务通过 openapi 属性识别 OpenAPI 文件，并激活专门处理。
• 结构验证： 在翻译过程中，验证模式以确保它是有效的 OpenAPI 规范。如果出现任何结构问题，将重试翻译以修复它们。
• 选择性翻译： AI 理解技术标识符和人类可读内容之间的语义差异。只有人类可读字段会被翻译，而技术标识符保持不变。

示例：什么被翻译

翻译前（英语）：

{
  "paths": {
    "/users/{userId}/profile": {
      "parameters": [
        {
          "name": "userId",
          "in": "path",
          "description": "The unique identifier of the user",
          "schema": { "type": "string" }
        }
      ]
    }
  },
  "components": {
    "schemas": {
      "UserStatus": {
        "type": "string",
        "enum": ["active", "inactive", "pending"],
        "description": "The current status of the user account"
      }
    }
  }
}

翻译后为日语：

{
  "paths": {
    "/users/{userId}/profile": {
      "parameters": [
        {
          "name": "userId",
          "in": "path",
          "description": "ユーザーの一意の識別子",
          "schema": { "type": "string" }
        }
      ]
    }
  },
  "components": {
    "schemas": {
      "UserStatus": {
        "type": "string",
        "enum": ["active", "inactive", "pending"],
        "description": "ユーザーアカウントの現在のステータス"
      }
    }
  }
}

数据类型保留

OpenAPI 本地化的一个关键方面是保持 JSON 数据类型。该服务确保：

• 数字保持数字（不转换为字符串）
• 布尔值保持 true/false（不翻译为单词）
• 空值保持 null（不转换为文本）

例如，这个具有各种数据类型的模式：

{
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 123
          },
          "price": {
            "type": "number",
            "example": 29.99
          },
          "inStock": {
            "type": "boolean",
            "example": true
          },
          "discount": {
            "type": "number",
            "nullable": true,
            "example": null
          }
        }
      }
    }
  }
}

翻译后的规范将准确保留所有这些类型——确保规范保持有效，并且可以安全地在生产中使用，而不会破坏 API 客户端或文档生成器。

与 VS Code 无缝集成

通过 VS Code 扩展，翻译 OpenAPI 规范可以无缝进行，让您直接在开发环境中本地化 API 文档。

在 VS Code 中的工作原理：

1. 打开您的 OpenAPI 规范文件（openapi.json 或 openapi.yaml）
2. 在编辑器中右键单击并选择 "翻译 JSON"
3. 选择目标语言（例如，日语、德语、西班牙语）
4. 扩展创建一个本地化版本，所有描述都被翻译，同时保持精确结构

查看实际效果

这是一个实时示例，展示如何在 VS Code 中将英语 OpenAPI 规范翻译为日语：

对开发者的好处

• 无损坏的规范： 翻译后的 OpenAPI 文件保持 100% 有效，可以在 Swagger UI、Redoc、Scalar 或任何 OpenAPI 工具中使用，而无需修改。
• 无手动修复： 字段名称、枚举值、$ref 路径和模式类型从不被更改——消除了翻译后清理的需要。
• 上下文感知的描述： AI 理解您的 API 的上下文，并用适当的技术术语和语气翻译描述。

OpenAPI 本地化的用例

本地化您的 OpenAPI 规范对于以下情况特别有价值：

公共 API 文档

如果您正在为全球开发者构建公共 API，提供多语言文档会显著提高采用率。当文档以开发者的母语提供时，他们更有可能集成 API。

开发者入职

本地化的 API 规范可以加快国际团队的入职速度。新开发者可以在没有语言障碍的情况下理解端点、参数和模式。

多语言团队

如果您的开发团队跨越多个国家，拥有每个团队成员语言的 API 文档可以改善协作并减少误沟通。

开始使用

准备好本地化您的 OpenAPI 规范了吗？您有两个选择：