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 ローカリゼーションの重要な側面の1つは、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. エディタ内で右クリックし、「Translate JSON」を選択します
3. ターゲット言語を選択します（例: 日本語、ドイツ語、スペイン語）
4. 拡張機能は、正確な構造を維持しながら、すべての説明が翻訳されたローカライズ版を作成します

実際の動作を見る

VS Code 内で英語の OpenAPI 仕様を日本語に翻訳するライブ例です:

開発者向けのメリット

• 仕様が壊れない: 翻訳された OpenAPI ファイルは 100% 有効なままであり、修正なしで Swagger UI、Redoc、Scalar、またはその他の OpenAPI ツールで使用できます。
• 手動修正が不要: フィールド名、enum 値、$ref パス、スキーマ型は決して変更されないため、翻訳後のクリーンアップ作業が不要になります。
• コンテキストを認識した説明: AI は API のコンテキストを理解し、適切な技術用語とトーンで説明を翻訳します。

OpenAPI ローカリゼーションのユースケース

OpenAPI 仕様のローカリゼーションは、特に以下の場合に価値があります:

公開 API ドキュメント

世界中の開発者向けに公開 API を構築している場合、多言語でドキュメントを提供することで採用率が劇的に向上します。開発者は、ドキュメントが母国語であれば、API を統合する可能性が高くなります。

開発者のオンボーディング

ローカライズされた API 仕様により、国際チームのオンボーディングが迅速化されます。新しい開発者は、言語の壁なしにエンドポイント、パラメータ、スキーマを理解できます。

多言語チーム

開発チームが複数の国にまたがっている場合、各チームメンバーの言語で API ドキュメントを持つことで、コラボレーションが改善され、コミュニケーションミスが減少します。

はじめに

OpenAPI 仕様をローカライズする準備はできましたか？2つのオプションがあります: