如何本地化 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 規範了嗎？您有兩個選擇：