如何本地化 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 值保持 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. 在編輯器中按右鍵並選擇「翻譯 JSON」
3. 選擇您的目標語言（例如：日語、德語、西班牙語）
4. 擴充功能會建立一個本地化版本，翻譯所有說明，同時保留精確的結構

查看實際操作

以下是在 VS Code 中將英語 OpenAPI 規範翻譯為日語的即時範例：

對開發者的好處

• 規範不會損壞： 翻譯後的 OpenAPI 檔案保持 100% 有效，無需修改即可用於 Swagger UI、Redoc、Scalar 或任何 OpenAPI 工具。
• 無需手動修復： 欄位名稱、列舉值、$ref 路徑和結構型別永遠不會被更改——消除了翻譯後清理的需求。
• 語境感知說明： AI 理解您的 API 語境，並以適當的技術術語和語氣翻譯說明。

OpenAPI 本地化的使用案例

本地化您的 OpenAPI 規範特別適用於：

公開 API 文件

如果您正在為全球開發者構建公開 API，提供多種語言的文件可顯著提高採用率。當文件使用母語時，開發者更有可能整合 API。

開發者入門

本地化的 API 規範使國際團隊的入門速度更快。新開發者可以理解端點、參數和結構，而不會有語言障礙。

多語言團隊

如果您的開發團隊跨越多個國家，擁有每位團隊成員母語的 API 文件可以改善協作並減少溝通誤解。

快速入門

準備好本地化您的 OpenAPI 規範了嗎？您有兩個選擇：