次の方法で共有

Translator 3.0:Languages

Translator の他の操作で現在サポートされている言語のセットを取得します。

リクエストURL

GET 要求の送信先は次のとおりです。

https://api.cognitive.microsofttranslator.com/languages?api-version=3.0

仮想ネットワークの場合は、カスタム ドメイン エンドポイントを使用します。

https://<your-custom-domain>.cognitiveservices.azure.com/languages?api-version=3.0

詳細については、「Virtual Network Support for Translator service selected network and private endpoint configuration and support.」(Translator サービスで選択されたネットワークとプライベート エンドポイントの構成とサポートについて) を参照してください。

要求パラメーター

クエリ文字列に渡される要求パラメーターを次に示します。

クエリ パラメーター 説明
APIバージョン 必須パラメーター

クライアントによって要求される API のバージョン。 値は 3.0 とする必要があります。
範囲 "省略可能なパラメーター"。

返される言語のグループを定義する名前のコンマ区切りのリスト。 許可されるグループ名は、translation、transliteration、および dictionary です。 スコープが指定されていない場合は、すべてのグループが返されます。これは、scope=translation,transliteration,dictionary渡すことと同じです。

本文応答を参照してください。

要求ヘッダーを次に示します。

ヘッダー 説明
Accept-Language "省略可能な要求ヘッダー"。

ユーザー インターフェイス文字列に使用する言語。 応答の一部のフィールドは、言語の名前または地域の名前です。 このパラメーターを使用して、これらの名前が返される言語を定義します。 言語は、整形式の BCP 47 言語タグを指定することによって指定されます。 たとえば、fr 値を使用してフランス語で名前を要求したり、zh-Hant 値を使用して繁体字中国語で名前を要求したりできます。
ターゲット言語が指定されていない場合、またはローカライズされた言語を利用できない場合、名前は英語で提供されます。
X-ClientTraceId "省略可能な要求ヘッダー"。
要求を一意に識別するためのクライアントによって生成された GUID。

言語リソースを取得するのに認証は必要ありません。

応答内容

クライアントは、 scope クエリ パラメーターを使用して、一覧表示する言語のグループを定義します。

  • scope=translation は、ある言語から別の言語にテキストを翻訳するためにサポートされる言語を提供します。

  • scope=transliteration は、ある言語のテキストを、ある書記体系から別の書記体系に変換する機能を提供します。

  • scope=dictionary は、Dictionary 操作がデータを返す言語ペアを提供します。

クライアントは、コンマ区切りの名前のリストを指定することによって、複数のグループを同時に取得できます。 たとえば、scope=translation,transliteration,dictionary は、すべてのグループに対してサポートされている言語を返します。

正常な応答は、要求されたグループごとに 1 つのプロパティを持つ JSON オブジェクトです。

{
    "translation": {
        //... set of languages supported to translate text (scope=translation)
    },
    "transliteration": {
        //... set of languages supported to convert between scripts (scope=transliteration)
    },
    "dictionary": {
        //... set of languages supported for alternative translations and examples (scope=dictionary)
    }
}

各プロパティの値は次のとおりです。

  • translation プロパティ

    translation プロパティの値は、キーと値のペアの辞書です。 各キーは、 BCP 47 言語タグです。 キーは、テキストの翻訳元または翻訳元の言語を識別します。 キーに関連付けられる値は、言語を表すプロパティを持つ JSON オブジェクトです。

    • name:Accept-Language ヘッダー経由で要求されたロケールの言語の表示名。

    • nativeName:この言語にネイティブなロケールの言語の表示名。

    • dir:方向性。右から左に記述する言語の場合は rtl、左から右に記述する言語の場合は ltr。

    例を示します。

    {
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}

  • transliteration プロパティ

    transliteration プロパティの値は、キーと値のペアの辞書です。 各キーは、 BCP 47 言語タグです。 キーは、あるスクリプトから別のスクリプトにテキストを変換できる言語を識別します。 キーに関連付けられる値は、言語とそのサポートされる書記体系を表すプロパティを持つ JSON オブジェクトです。

    • name:Accept-Language ヘッダー経由で要求されたロケールの言語の表示名。

    • nativeName:この言語にネイティブなロケールの言語の表示名。

    • scripts:変換元の書記体系の一覧。 scripts の一覧の各要素には、次のプロパティがあります。

      • code:書記体系を識別するコード。

      • name:Accept-Language ヘッダー経由で要求されたロケールの書記体系の表示名。

      • nativeName:この言語にネイティブなロケールの言語の表示名。

      • dir:方向性。右から左に記述する言語の場合は rtl、左から右に記述する言語の場合は ltr。

      • toScripts:テキストの変換先として使用できる書記体系の一覧。 toScripts の一覧の各要素には、前述したとおり code、name、nativeName、dir の各プロパティがあります。

    例を示します。

    {
  "transliteration": {
    ...
    "ja": {
      "name": "Japanese",
      "nativeName": "日本語",
      "scripts": [
        {
          "code": "Jpan",
          "name": "Japanese",
          "nativeName": "日本語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Latn",
              "name": "Latin",
              "nativeName": "ラテン語",
              "dir": "ltr"
            }
          ]
        },
        {
          "code": "Latn",
          "name": "Latin",
          "nativeName": "ラテン語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Jpan",
              "name": "Japanese",
              "nativeName": "日本語",
              "dir": "ltr"
            }
          ]
        }
      ]
    },
    ...
  }
}

  • dictionary プロパティ

    dictionary プロパティの値は、キーと値のペアの辞書です。 各キーは、 BCP 47 言語タグです。 キーは、代替翻訳と逆翻訳が利用可能な言語を識別します。 値は、ソース言語と利用可能な翻訳があるターゲット言語を記述する JSON オブジェクトです。

    • name:Accept-Language ヘッダー経由で要求されたロケールのソース言語の表示名。

    • nativeName:この言語にネイティブなロケールの言語の表示名。

    • dir:方向性。右から左に記述する言語の場合は rtl、左から右に記述する言語の場合は ltr。

    • translations: ソース言語で表されるクエリの代替翻訳と例を含む言語の一覧。 translations の一覧の各要素には、次のプロパティがあります。

      • name:Accept-Language ヘッダー経由で要求されたロケールのターゲット言語の表示名。

      • nativeName:ターゲット言語にネイティブなロケールのターゲット言語の表示名。

      • dir:方向性。右から左に記述する言語の場合は rtl、左から右に記述する言語の場合は ltr。

      • code:ターゲット言語を識別する言語コード。

    例を示します。

    "es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},

応答オブジェクトの構造は、API のバージョンを変更しなければ変更されません。 同じバージョンの API の場合、使用可能な言語の一覧が時間の経過と共に変更される可能性があります。これは、Microsoft Translator のサービスでサポートされる言語の一覧が絶えず拡張されているためです。

サポートされている言語のリストは頻繁には変更されません。 ネットワーク帯域幅を節約し、応答性を向上させるために、クライアント アプリケーションでは、言語リソースと対応するエンティティ タグ (ETag) をキャッシュすることを検討する必要があります。 次に、クライアント アプリケーションは、定期的に (たとえば、24 時間に 1 回) サービスに対するクエリを実行して、サポートされている言語の最新のセットをフェッチすることができます。 現在の ETag 値を If-None-Match ヘッダー フィールドで渡すことで、サービスは応答を最適化できます。 リソースが変更されていない場合、サービスは状態コード 304 と空の応答本文を返します。

応答ヘッダー

ヘッダー 説明
ETag サポートされている言語の要求されたグループのエンティティ タグの現在の値。 後続の要求をより効率的にするために、クライアントは ETag ヘッダー フィールドに If-None-Match 値を送信できます。
X-RequestId 要求を識別するためにサービスによって生成される値。 トラブルシューティングの目的で使用されます。

応答状態コード

要求によって返される可能性のある HTTP 状態コードを次に示します。

状態コード 説明
200 成功。
304 リソースは変更されず、要求ヘッダー If-None-Matchで指定されたバージョンに合わせて調整されます。
400 クエリ パラメーターの 1 つが欠落しているか無効です。 再試行する前に要求パラメーターを修正してください。
429 クライアントが要求の制限を超えたため、サーバーは要求を拒否しました。
500 予期しないエラーが発生しました。 エラーが解決しない場合は、エラー発生の日時、応答ヘッダー X-RequestId からの要求識別子、要求ヘッダー X-ClientTraceId からのクライアント識別子を添えてその旨をご報告ください。
503 サーバーが一時的に使用できません。 要求をやり直してください。 エラーが解決しない場合は、エラー発生の日時、応答ヘッダー X-RequestId からの要求識別子、要求ヘッダー X-ClientTraceId からのクライアント識別子を添えてその旨をご報告ください。

エラーが発生した場合、要求から JSON エラー応答も返されます。 このエラーコードは 3 桁の HTTP ステータス コードの後に､エラーをさらに分類するための 3 桁の数字を続けた 6 桁の数字です｡ 一般的なエラー コードは、v3 Translator のリファレンス ページで確認できます。

例示

次の例では、テキスト翻訳でサポートされている言語を取得する方法を示します。

curl "https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"

関連コンテンツ

詳しくは、言語のサポートに関する記事をご覧ください。