如何本地化 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 的无缝集成

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

在 VS Code 中如何工作：

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

查看实际操作

以下是在 VS Code 中将英语 OpenAPI 规范翻译为日语的实时示例：

对开发者的好处

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

OpenAPI 本地化的用例

本地化您的 OpenAPI 规范特别适用于：

公共 API 文档

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

开发者入职

本地化的 API 规范使国际团队的入职更快。新开发者可以理解端点、参数和模式，而无需语言障碍。

多语言团队

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

入门指南

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