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 サービスで選択されたネットワークとプライベート エンドポイントの構成とサポートについて) を参照してください。

要求パラメーター

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

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

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

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

応答の本文

クライアントは、 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 と空の応答本文を返します。

応答ヘッダー

応答状態コード

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

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

例

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

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