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データ型を維持することです。サービスは以下を保証します:

• 数値は数値のまま（文字列に変換されない）
• ブール値は真/偽のまま（単語に翻訳されない）
• ヌル値はヌルのまま（テキストに変換されない）

例えば、さまざまなデータ型を持つこのスキーマ:

{
  "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仕様をローカライズする準備はできましたか？ 2つのオプションがあります: