Translator Text API 3.0: LanguagesTranslator Text API 3.0: Languages

Translator Text API の他の操作で現在サポートされている一連の言語を取得します。Gets the set of languages currently supported by other operations of the Translator Text API.

要求 URLRequest URL

GET 要求の送信先は次のとおりです。Send a GET request to:

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

要求パラメーターRequest parameters

クエリ文字列に渡される要求パラメーターを次に示します。Request parameters passed on the query string are:

Query parameter (クエリ パラメーター)Query parameter 説明Description
api-versionapi-version "必須のパラメーター"。Required parameter.
クライアントによって要求される API のバージョン。Version of the API requested by the client. 値は `3.0` とする必要があります。Value must be `3.0`.
scopescope "*省略可能なパラメーター*"。*Optional parameter*.
取得する言語のグループを定義する名前のコンマ区切りのリスト。A comma-separated list of names defining the group of languages to return. 許可されるグループ名は、`translation`、`transliteration`、および `dictionary` です。Allowed group names are: `translation`, `transliteration` and `dictionary`. スコープを指定しない場合は、すべてのグループが返されます。これは、`scope=translation,transliteration,dictionary` を渡すのと等価です。If no scope is given, then all groups are returned, which is equivalent to passing `scope=translation,transliteration,dictionary`. サポートされている言語のどのセットが自分のシナリオに適しているかを判断するには、[応答オブジェクト](#response-body)の説明を参照してください。To decide which set of supported languages is appropriate for your scenario, see the description of the [response object](#response-body).

要求ヘッダーを次に示します。Request headers are:

headersHeaders 説明Description
Accept-LanguageAccept-Language "*省略可能な要求ヘッダー*"。*Optional request header*.
ユーザー インターフェイス文字列に使用する言語。The language to use for user interface strings. 応答内のフィールドには、言語の名前やリージョンの名前などがあります。Some of the fields in the response are names of languages or names of regions. これらの名前が返される言語を定義するには、このパラメーターを使用します。Use this parameter to define the language in which these names are returned. 言語は、整形式の BCP 47 言語タグを使用して指定します。The language is specified by providing a well-formed BCP 47 language tag. たとえば、フランス語の名前を要求するには値 `fr` を使用し、繁体字中国語の名前を要求するには値 `zh-Hant` を使用します。For instance, use the value `fr` to request names in French or use the value `zh-Hant` to request names in Chinese Traditional.
ターゲット言語が指定されていない場合、またはローカライズされた言語を利用できない場合、名前は英語で提供されます。Names are provided in the English language when a target language is not specified or when localization is not available.
X-ClientTraceIdX-ClientTraceId "*省略可能な要求ヘッダー*"。*Optional request header*.
要求を一意に識別する、クライアントで生成された GUID。A client-generated GUID to uniquely identify the request.

言語リソースを取得するのに認証は必要ありません。Authentication isn't required to get language resources.

応答本文Response body

クライアントは、scope クエリ パラメーターを使用して、目的の言語のグループを定義します。A client uses the scope query parameter to define which groups of languages it's interested in.

  • scope=translation は、ある言語から別の言語にテキストを翻訳するためにサポートされる言語を提供します。scope=translation provides languages supported to translate text from one language to another language;

  • scope=transliteration は、ある言語のテキストを、ある書記体系から別の書記体系に変換する機能を提供します。scope=transliteration provides capabilities for converting text in one language from one script to another script;

  • scope=dictionary は、Dictionary 操作がデータを返す言語ペアを提供します。scope=dictionary provides language pairs for which Dictionary operations return data.

クライアントは、コンマ区切りの名前のリストを指定することによって、複数のグループを同時に取得できます。A client may retrieve several groups simultaneously by specifying a comma-separated list of names. たとえば、scope=translation,transliteration,dictionary は、すべてのグループに対してサポートされている言語を返します。For example, scope=translation,transliteration,dictionary would return supported languages for all groups.

正常な応答は、要求されたグループごとに 1 つのプロパティを持つ JSON オブジェクトです。A successful response is a JSON object with one property for each requested group:

{
    "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)
    }
}

各プロパティの値は次のとおりです。The value for each property is as follows.

  • translation プロパティtranslation property

    translation プロパティの値は、キーと値のペアの辞書です。The value of the translation property is a dictionary of (key, value) pairs. 各キーは BCP 47 言語タグです。Each key is a BCP 47 language tag. キーは、テキストの翻訳先の言語または元の言語を識別します。A key identifies a language for which text can be translated to or translated from. キーに関連付けられる値は、言語を表すプロパティを持つ JSON オブジェクトです。The value associated with the key is a JSON object with properties that describe the language:

    • name:Accept-Language ヘッダー経由で要求されたロケールの言語の表示名。name: Display name of the language in the locale requested via Accept-Language header.

    • nativeName:この言語にネイティブなロケールの言語の表示名。nativeName: Display name of the language in the locale native for this language.

    • dir:方向性。右から左に記述する言語の場合は rtl、左から右に記述する言語の場合は ltrdir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.

    例を示します。An example is:

    {
      "translation": {
        ...
        "fr": {
          "name": "French",
          "nativeName": "Français",
          "dir": "ltr"
        },
        ...
      }
    }
    
  • transliteration プロパティtransliteration property

    transliteration プロパティの値は、キーと値のペアの辞書です。The value of the transliteration property is a dictionary of (key, value) pairs. 各キーは BCP 47 言語タグです。Each key is a BCP 47 language tag. キーは、テキストをある書記体系から別の書記体系に変換できる言語を示します。A key identifies a language for which text can be converted from one script to another script. キーに関連付けられる値は、言語とそのサポートされる書記体系を表すプロパティを持つ JSON オブジェクトです。The value associated with the key is a JSON object with properties that describe the language and its supported scripts:

    • name:Accept-Language ヘッダー経由で要求されたロケールの言語の表示名。name: Display name of the language in the locale requested via Accept-Language header.

    • nativeName:この言語にネイティブなロケールの言語の表示名。nativeName: Display name of the language in the locale native for this language.

    • scripts:変換元の書記体系の一覧。scripts: List of scripts to convert from. scripts の一覧の各要素には、次のプロパティがあります。Each element of the scripts list has properties:

      • code:書記体系を識別するコード。code: Code identifying the script.

      • name:Accept-Language ヘッダー経由で要求されたロケールの書記体系の表示名。name: Display name of the script in the locale requested via Accept-Language header.

      • nativeName:この言語にネイティブなロケールの言語の表示名。nativeName: Display name of the language in the locale native for the language.

      • dir:方向性。右から左に記述する言語の場合は rtl、左から右に記述する言語の場合は ltrdir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.

      • toScripts:テキストの変換先として使用できる書記体系の一覧。toScripts: List of scripts available to convert text to. toScripts の一覧の各要素には、前述したとおり codenamenativeNamedir の各プロパティがあります。Each element of the toScripts list has properties code, name, nativeName, and dir as described earlier.

    例を示します。An example is:

    {
      "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 property

    dictionary プロパティの値は、キーと値のペアの辞書です。The value of the dictionary property is a dictionary of (key, value) pairs. 各キーは BCP 47 言語タグです。Each key is a BCP 47 language tag. キーは、代替翻訳と逆翻訳が利用可能な言語を識別します。The key identifies a language for which alternative translations and back-translations are available. 値は、ソース言語と利用可能な翻訳があるターゲット言語を記述する JSON オブジェクトです。The value is a JSON object that describes the source language and the target languages with available translations:

    • name:Accept-Language ヘッダー経由で要求されたロケールのソース言語の表示名。name: Display name of the source language in the locale requested via Accept-Language header.

    • nativeName:この言語にネイティブなロケールの言語の表示名。nativeName: Display name of the language in the locale native for this language.

    • dir:方向性。右から左に記述する言語の場合は rtl、左から右に記述する言語の場合は ltrdir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.

    • translations:代替翻訳とソース言語で表現されたクエリの例を含む言語の一覧。translations: List of languages with alterative translations and examples for the query expressed in the source language. translations の一覧の各要素には、次のプロパティがあります。Each element of the translations list has properties:

      • name:Accept-Language ヘッダー経由で要求されたロケールのターゲット言語の表示名。name: Display name of the target language in the locale requested via Accept-Language header.

      • nativeName:ターゲット言語にネイティブなロケールのターゲット言語の表示名。nativeName: Display name of the target language in the locale native for the target language.

      • dir:方向性。右から左に記述する言語の場合は rtl、左から右に記述する言語の場合は ltrdir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.

      • code:ターゲット言語を識別する言語コード。code: Language code identifying the target language.

    例を示します。An example is:

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

応答オブジェクトの構造は、API のバージョンを変更しなければ変更されません。The structure of the response object will not change without a change in the version of the API. 同じバージョンの API の場合、使用可能な言語の一覧が時間の経過と共に変更される可能性があります。これは、Microsoft Translator のサービスでサポートされる言語の一覧が絶えず拡張されているためです。For the same version of the API, the list of available languages may change over time because Microsoft Translator continually extends the list of languages supported by its services.

サポートされている言語の一覧は頻繁には変更されません。The list of supported languages will not change frequently. ネットワーク帯域幅を節約し、応答性を向上させるために、クライアント アプリケーションでは、言語リソースと対応するエンティティ タグ (ETag) をキャッシュすることを検討する必要があります。To save network bandwidth and improve responsiveness, a client application should consider caching language resources and the corresponding entity tag (ETag). 次に、クライアント アプリケーションは、定期的に (たとえば、24 時間に 1 回) サービスに対するクエリを実行して、サポートされている言語の最新のセットをフェッチすることができます。Then, the client application can periodically (for example, once every 24 hours) query the service to fetch the latest set of supported languages. 現在の ETag 値を If-None-Match ヘッダー フィールドで渡すことで、サービスは応答を最適化できます。Passing the current ETag value in an If-None-Match header field will allow the service to optimize the response. リソースが変更されていない場合、サービスは状態コード 304 と空の応答本文を返します。If the resource has not been modified, the service will return status code 304 and an empty response body.

応答ヘッダーResponse headers

headersHeaders 説明Description
ETagETag 要求されたサポートされる言語のグループのエンティティ タグの現在の値。Current value of the entity tag for the requested groups of supported languages. 後続の要求をより効率的にするために、クライアントは、`If-None-Match` ヘッダー フィールドで `ETag` 値を送信することができます。To make subsequent requests more efficient, the client may send the `ETag` value in an `If-None-Match` header field.
X-RequestIdX-RequestId 要求を識別するためにサービスによって生成される値。Value generated by the service to identify the request. トラブルシューティングの目的で使用されます。It is used for troubleshooting purposes.

応答状態コードResponse status codes

要求によって返される可能性のある HTTP 状態コードを次に示します。The following are the possible HTTP status codes that a request returns.

状態コードStatus Code 説明Description
200200 成功。Success.
304304 リソースは、要求ヘッダー `If-None-Match` で指定されたバージョン以降変更されていません。The resource has not been modified since the version specified by request headers `If-None-Match`.
400400 クエリ パラメーターの 1 つが欠落しているか無効です。One of the query parameters is missing or not valid. 再試行する前に要求パラメーターを修正してください。Correct request parameters before retrying.
429429 クライアントが要求の制限を超えたため、サーバーは要求を拒否しました。The server rejected the request because the client has exceeded request limits.
500500 予期しないエラーが発生しました。An unexpected error occurred. エラーが解決しない場合は、エラー発生の日時、応答ヘッダー `X-RequestId` からの要求識別子、要求ヘッダー `X-ClientTraceId` からのクライアント識別子を添えてその旨をご報告ください。If the error persists, report it with: date and time of the failure, request identifier from response header `X-RequestId`, and client identifier from request header `X-ClientTraceId`.
503503 サーバーが一時的に使用できません。Server temporarily unavailable. 要求をやり直してください。Retry the request. エラーが解決しない場合は、エラー発生の日時、応答ヘッダー `X-RequestId` からの要求識別子、要求ヘッダー `X-ClientTraceId` からのクライアント識別子を添えてその旨をご報告ください。If the error persists, report it with: date and time of the failure, request identifier from response header `X-RequestId`, and client identifier from request header `X-ClientTraceId`.

エラーが発生した場合は、要求の結果として JSON エラー応答も返されます。If an error occurs, the request will also return a JSON error response. このエラーコードは 3 桁の HTTP ステータス コードの後に、エラーをさらに分類するための 3 桁の数字を続けた 6 桁の数字です。The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. 一般的なエラー コードは、v3 Translator Text API のリファレンス ページで確認できます。Common error codes can be found on the v3 Translator Text API reference page.

Examples

次の例では、テキスト翻訳でサポートされている言語を取得する方法を示します。The following example shows how to retrieve languages supported for text translation.

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