Azure REST API TextTranslation 2026-06-06とは？変更点と移行確認ポイント

Azure REST APIの「Azure REST API documentation update: [TextTranslation] Add API version 2026-06-06」は、Azure TranslatorのText Translation APIに新しいGA APIバージョン 2026-06-06 を追加する更新です。結論から言うと、2025-10-01-preview を使っている開発者は、単に api-version を置き換えるだけでなく、grade パラメーターの利用有無、tone と gender の型、SDK生成コード、認証設定、監視ログを確認してから段階的に展開する必要があります。

公式PRでは当初「Public Preview API version 2025-10-01-preview の後継としてGA API version 2026-06-06 をリリースする」と説明されています。一方で、最終的なPRには BreakingChange-Approved-UserImpact ラベルが付いており、レビューコメントでも「プロパティ削除は破壊的変更」と指摘されています。つまり、GA化されたから安全に一括置換できる、とは考えない方がよい更新です。(GitHub)

Azure REST APIのTextTranslation 2026-06-06で何が変わるのか

今回の更新は、Azure REST API仕様リポジトリにおけるTextTranslationの新しい安定版API追加です。PRはAzure/azure-rest-api-specsの main ブランチへ2026年5月19日にマージされ、stable/2026-06-06/openapi.json が追加されています。README上でも現在のリリースは package-2026-06-06 とされ、stable/2026-06-06/openapi.json が入力ファイルとして指定されています。(GitHub)

確認項目	内容	実務での対応
APIバージョン	`2026-06-06` がGA版として追加	`api-version=2026-06-06` で検証環境からテスト
位置づけ	`2025-10-01-preview` の後継	preview利用中のコードを棚卸し
対象API	`/languages`、`/translate`、`/transliterate`	既存の翻訳・表記変換・対応言語取得処理を確認
仕様ファイル	`stable/2026-06-06/openapi.json`	OpenAPI/SDK生成パイプラインを更新
注意点	`grade` 削除、`tone`・`gender` のenum化などに注意	preview互換を前提にせずテストする

特に重要なのは、今回の更新が「新しいAPIバージョン番号の追加」に見える一方で、preview版との細かな差分がアプリケーションやSDK生成に影響する可能性がある点です。PR内では「GAでの変更は新しいAPIバージョン番号」と説明された箇所がありますが、後続コミットでは grade の削除や tone、gender のenum化が行われています。(GitHub)

対象となるText Translation API

2026-06-06 のOpenAPI仕様では、Text Translation APIとして主に次のパスが定義されています。各リクエストでは api-version クエリパラメーターが必須です。(GitHub)

パス	メソッド	用途
`/languages`	GET	翻訳や表記変換で利用できる対応言語情報を取得
`/translate`	POST	入力テキストを指定したターゲット言語へ翻訳
`/transliterate`	POST	文字体系やアルファベットを別のスクリプトへ変換

Microsoft LearnのText Translation REST APIガイドでも、言語取得、翻訳、表記変換などのメソッドが紹介されています。/languages は対応言語セットを返すAPIで、翻訳処理の前提データ確認にも使えます。(Microsoft Learn)

呼び出し例

実際の移行テストでは、既存のpreview呼び出しを残したまま、検証環境で api-version=2026-06-06 を指定して差分を確認します。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=2026-06-06" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "Content-Type: application/json" \
  -H "X-ClientTraceId: <client-generated-guid>" \
  -d '{
    "inputs": [
      {
        "text": "This is a test.",
        "language": "en",
        "textType": "Plain",
        "targets": [
          {
            "language": "ja"
          }
        ]
      }
    ]
  }'

仕様上の認証定義には、APIキーを使う Ocp-Apim-Subscription-Key と、Microsoft Entra IDのOAuth2認証が含まれています。既存システムでAPIキー、Entra ID、API Management経由の認証を使っている場合は、OpenAPI更新後の生成クライアントやゲートウェイ設定が同じ方式で通るか確認してください。(GitHub)

preview版から移行する開発者が最初に見るべきポイント

`api-version` を固定している場所を棚卸しする

Azure REST APIでは、サービス仕様に応じてURIやクエリ文字列にAPIバージョンを指定します。TextTranslationの 2026-06-06 仕様でも api-version は必須パラメーターです。(Microsoft Learn)

まずはリポジトリ全体で次の文字列を検索してください。

2025-10-01-preview
api-version=
TextTranslation
azure-ai-translation-text
@azure-rest/ai-translation-text

確認対象はアプリケーションコードだけではありません。次の場所にも古いバージョンが残りやすいです。

API ManagementのバックエンドURL
Logic AppsやPower AutomateのHTTPアクション
CI/CDの環境変数
OpenAPIから自動生成したクライアントコード
テストコード内の期待値
Postman、Insomnia、curlサンプル
社内ドキュメントや運用手順書

特にAPI Managementで api-version をポリシー側で付与している場合、アプリ側を更新してもゲートウェイで古いpreview版に戻されることがあります。

`grade` パラメーターを使っていないか確認する

preview版の仕様には、翻訳ターゲット設定の中に grade が定義されていました。一方、2026-06-06 の安定版仕様では grade が見当たらず、PRの後半でも remove grade に関するコミットが確認できます。(GitHub)

次のようなリクエストを送っている場合は要注意です。

{
  "inputs": [
    {
      "text": "This is a test.",
      "language": "en",
      "targets": [
        {
          "language": "ja",
          "grade": "basic"
        }
      ]
    }
  ]
}

2026-06-06 へ移行する前に、grade を指定している箇所を削除するか、代替設定が必要かを確認してください。SDKを使っている場合は、コンパイルエラーや型定義エラーとして検出できる可能性があります。RESTを直接呼んでいる場合は、リクエストが実行時まで失敗しないこともあるため、統合テストで必ず確認します。

`tone` と `gender` は自由文字列ではなくenumとして扱う

2026-06-06 の仕様では、tone は neutral、formal、informal、gender は neutral、male、female のenumとして定義されています。preview版ではこれらがより緩い文字列として扱われていたため、独自の値や大文字小文字の揺れを使っていた場合は修正が必要です。(GitHub)

項目	`2026-06-06` で使える値	確認すべき例
`tone`	`neutral`、`formal`、`informal`	`Formal`、`business`、`casual` など独自値を送っていないか
`gender`	`neutral`、`male`、`female`	`none`、`unknown`、`masculine` などを使っていないか

実務では、フロントエンドのプルダウン、バックエンドのバリデーション、SDKの型定義を同時に更新する必要があります。APIだけ更新してUI側に古い選択肢が残ると、ユーザー操作でエラーが発生します。

`deploymentName` と `allowFallback` の扱いを確認する

2026-06-06 の仕様では、翻訳ターゲット設定に deploymentName と allowFallback が含まれています。deploymentName の既定値は general と説明され、例としてGPT-4oやGPT-4o miniに関連するデプロイ名が示されています。また、allowFallback は既定で true とされ、カスタムシステムやLLM利用時のフォールバック動作に関わります。(GitHub)

ここで失敗しやすいのは、品質を固定したいからといって allowFallback=false を安易に指定するケースです。カスタムモデルや特定デプロイが存在しない、または言語ペアに対応していない場合、リクエストがエラーになる可能性があります。重要な業務翻訳で「品質を固定する」ことは大切ですが、その場合は次のように運用設計まで含めて決めてください。

判断ポイント	`allowFallback=true` が向くケース	`allowFallback=false` が向くケース
可用性	翻訳処理を止めたくない	想定外モデルでの翻訳を禁止したい
品質管理	一定の結果が返ることを優先	指定モデル・指定カスタム翻訳のみ許可
エラー時対応	自動継続を重視	明示的に失敗させ、再処理や人手確認へ回す
運用例	社内FAQ、チャット補助	契約書、製品文書、規制対象文書

対応言語をハードコードしている場合は `/languages` を再確認する

/languages は、翻訳や表記変換で対応している言語情報を返すAPIです。仕様には ETag と If-None-Match の説明があり、対応言語情報が未変更の場合は効率的に取得できる仕組みが示されています。(GitHub)

対応言語をアプリ内に固定配列で持っている場合、API更新後に表示内容や利用可能なモデル情報とずれる可能性があります。特に翻訳対象言語をユーザーに選ばせるサービスでは、/languages の結果を定期的に取得し、キャッシュする構成が安全です。

実装の目安は次の通りです。

用途	推奨対応
管理画面の言語一覧	1日1回など定期更新し、ETagを活用
翻訳実行前のバリデーション	キャッシュした対応言語リストで事前チェック
多言語UI	`Accept-Language` を使い、表示名の言語を確認
障害調査	`X-ClientTraceId` とレスポンスの `X-RequestId` をログに残す

管理者が確認すべき設定と影響範囲

API Managementやプロキシで `api-version` を上書きしていないか

企業システムでは、アプリケーションから直接Azure Translatorへアクセスせず、Azure API Management、社内プロキシ、リバースプロキシ、サービスメッシュを経由していることがあります。この場合、移行時に最も見落としやすいのがURL変換です。

確認すべき設定は次の通りです。

設定箇所	確認内容
API Management inbound policy	`api-version` を固定値で追加・上書きしていないか
backend policy	接続先エンドポイントがTextTranslationの想定エンドポイントか
named values	preview版のURLやAPIバージョンが残っていないか
監査ログ	2026-06-06への切り替え後、実際に新APIバージョンへ到達しているか
WAF/プロキシ	新しいリクエスト本文のフィールドをブロックしていないか

アプリ側のコードだけ更新しても、ゲートウェイ側で api-version=2025-10-01-preview に戻されると、検証結果と本番結果が食い違います。

認証方式の扱いを再確認する

2026-06-06 のOpenAPI仕様では、APIキー認証とOAuth2認証が定義されています。APIキーを使う場合は Ocp-Apim-Subscription-Key、OAuth2では https://cognitiveservices.azure.com/.default スコープが記載されています。(GitHub)

管理者は次の観点を確認してください。

APIキーをKey Vaultやシークレット管理基盤から取得しているか
本番・検証・開発環境で異なるキーを使っているか
Entra ID認証を使う場合、サービスプリンシパルやマネージドIDの権限が適切か
キーやトークンをアプリログに出力していないか
API Managementでヘッダーを二重付与していないか

特にSDK生成後に認証コードを書き換える場合、既存のAPIキー方式からOAuth2方式へ意図せず変わっていないかを確認します。認証方式の変更はAPIバージョン変更よりも障害範囲が大きくなりやすいため、移行タスクを分けて管理するのが安全です。

コスト・利用量の監視を更新する

/translate のレスポンスヘッダーには、課金対象文字数を示す x-metered-usage が定義されています。また、翻訳結果には instructionTokens、sourceTokens、responseTokens、targetTokens など、トークン関連のフィールドも定義されています。(GitHub)

既存の監視が「リクエスト数」だけを見ている場合、API更新を機に次の指標も確認できるようにしておくと運用しやすくなります。

監視項目	目的
リクエスト数	急増・異常利用の検知
4xx/5xx率	移行後のリクエスト不備やサービス障害の検知
`x-metered-usage`	課金対象文字数の傾向把握
`X-RequestId`	Microsoftサポート問い合わせ時の調査材料
`X-ClientTraceId`	自社側ログとの突き合わせ
トークン関連フィールド	LLM関連の利用傾向や品質検証の参考

翻訳対象の本文をログに残す場合は、個人情報、機密情報、契約情報が含まれる可能性があります。障害調査用ログでは、本文そのものではなく、文字数、言語コード、リクエストID、エラーコードを中心に記録する設計が現実的です。

SDK利用者が注意すべき点

PRでは、APIレベルの変更チェックによりPython、Java、JavaScript、TypeSpec向けのAPIViewが作成されています。また、ファイル差分にはJavaクライアント名のカスタマイズも含まれています。(GitHub)

SDKを使っている場合、RESTのURLだけでなく、次の変化が起きる可能性があります。

影響箇所	起こり得る変化
型定義	`tone`、`gender` がenumとして扱われる
プロパティ名	Javaなど言語別に生成名が変わる可能性
コンストラクタ	APIバージョン指定方法が変わる可能性
シリアライズ	削除されたフィールドを送れなくなる
テスト	モックレスポンスの型不一致が発生する

SDK更新時は、パッケージを上げる前に「REST APIバージョンの変更」と「SDKメジャー/マイナーバージョンの変更」を分けて確認してください。SDKのリリースノートや生成PRが公開されている場合は、そちらも併せて確認する必要があります。

移行手順：安全に2026-06-06へ切り替える

本番環境でTextTranslationを使っている場合は、次の順序で進めると失敗を減らせます。

| 手順 | 作業 | 完了条件 |
| -: | ———————————– | ———————————————- |
| 1 | 2025-10-01-preview の利用箇所を検索 | コード、設定、ドキュメントの一覧化が完了 |
| 2 | grade、独自の tone、独自の gender を確認 | 削除・置換・バリデーション修正方針が決まる |
| 3 | 検証環境で api-version=2026-06-06 を指定 | /languages、/translate、/transliterate が通る |
| 4 | 代表的な言語ペアで応答を比較 | レスポンス形式、エラー、品質に問題がない |
| 5 | SDK利用箇所を更新 | コンパイル、単体テスト、統合テストが成功 |
| 6 | API Managementやプロキシ設定を更新 | 実ログで2026-06-06への到達を確認 |
| 7 | 小規模トラフィックでカナリア展開 | エラー率、課金対象文字数、レイテンシが許容範囲 |
| 8 | 本番切り替えとロールバック手順を確定 | preview版へ戻す条件と手順が明文化されている |

比較テストで見るべきリクエスト例

翻訳APIは、単純な英日翻訳だけでテストすると差分を見落とします。次のパターンを最低限確認してください。

テストケース	理由
英語から日本語の通常翻訳	基本動作の確認
日本語から英語の通常翻訳	双方向の品質とレスポンス確認
HTML入力	`textType=Html` の扱いを確認
複数ターゲット言語	`targets` 配列の処理を確認
`tone=formal`	enum化された値の確認
`gender=neutral`	enum化された値の確認
`deploymentName` 指定	モデル・カスタム設定の確認
`allowFallback=false`	エラー時の挙動確認
`/transliterate`	`language`、`fromScript`、`toScript` の必須指定確認
`/languages`	対応言語、ETag、キャッシュ挙動の確認

よくある失敗と回避策

GA版だからpreview版と完全互換だと思い込む

今回のPRでは、初期説明として「preview版とのAPI仕様差分なし」といった記述がある一方、最終的には破壊的変更に関するラベルやレビューコメントが残っています。特に grade を使っていた場合は、preview版と同じリクエストが通らない可能性を前提にしてください。(GitHub)

回避策は、単純なバージョン置換ではなく、実際のリクエスト本文を使った統合テストを行うことです。

対応言語リストを固定したままにする

言語一覧やモデル対応状況をアプリ側で固定していると、API仕様やサービス側の対応状況とずれる可能性があります。/languages の結果をキャッシュして使う構成にしておくと、将来の更新にも対応しやすくなります。

SDKだけ更新してAPI Managementを更新しない

SDK更新後にローカルテストは成功しても、本番ではAPI Managementが古い api-version を付けている場合があります。切り替え後は、アプリログだけでなく、ゲートウェイログやバックエンド到達ログで実際のクエリ文字列を確認してください。

翻訳本文をそのままログに残す

移行時は差分調査のためにログを増やしたくなりますが、翻訳対象テキストには個人情報や機密情報が含まれることがあります。ログに残すのは、原則としてリクエストID、言語コード、文字数、エラーコード、処理時間に限定し、本文は必要最小限にします。

展開前チェックリスト

本番へ反映する前に、次の項目を確認してください。

api-version=2025-10-01-preview の残存箇所を洗い出した
grade を送っているリクエストがない、または削除対応済み
tone は neutral、formal、informal のいずれかに制限した
gender は neutral、male、female のいずれかに制限した
/languages、/translate、/transliterate の代表ケースを検証した
SDK利用箇所でコンパイルエラーや型不一致がない
API Managementやプロキシで古いAPIバージョンを付与していない
X-ClientTraceId と X-RequestId を追跡できる
x-metered-usage やエラー率の監視を確認した
ロールバック時に戻すAPIバージョンと設定手順が決まっている

まず何をすべきか

Azure REST APIのTextTranslationで 2025-10-01-preview を使っているなら、最初に行うべきことは3つです。

まず、コードと設定から 2025-10-01-preview、grade、tone、gender を検索します。次に、検証環境で api-version=2026-06-06 を指定し、実際の翻訳リクエストでレスポンスとエラーを比較します。最後に、SDKやAPI Managementを含む展開経路全体で、同じAPIバージョンに到達しているかをログで確認します。

今回の更新は、単なるドキュメント上のバージョン追加ではなく、previewからGAへ移行するための実務的な節目です。管理者は認証・ゲートウェイ・監視を確認し、開発者はリクエスト本文・型定義・SDK生成コードを確認することで、安全に 2026-06-06 へ移行できます。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。