Translate text

To translate a text, use the translate method.

Examples

To try the examples in this section:

  1. On the billing page, make sure that the payment account has the ACTIVE or TRIAL_ACTIVE status. If you don't have a payment account, create one.
  2. Make sure you have installed the cURL utility that is used in the examples.
  3. Get the ID of any folder that your account is granted the editor role or higher for.
  4. Get an IAM token for your Yandex account.

To perform these operations on behalf of the service account:

  1. Assign the editor role or a higher role to the service account for the folder where it was created.
  2. Do not specify the folder ID in the request: the service uses the folder where the service account was created.
  3. Choose the authentication method: get an IAM token or API key.

Hello, world

In this example, we will translate two text strings into Russian: Hello and World.

  1. Use the listLanguages method to get the code of the target language:

    $ export IAM_TOKEN=CggaATEVAgA...
    $ curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer ${IAM_TOKEN}" \
        -d "{\"folder_id\": \"${FOLDER_ID}\"}" \
        "https://translate.api.cloud.yandex.net/translate/v2/languages"
    

    The response will contain a list of language names in the corresponding language:

    {
        "languages": [
            ...
            {
            "code": "ru",
            "name": "Russian"
            },
            ...
        ]
    }
    
  2. Create a file with the request body (for example, body.json). List the text strings to translate in the texts field. Specify the target language in the targetLanguageCode field.

    {
        "folder_id": "b1gvmob95yysaplct532",
        "texts": ["Hello", "World"],
        "targetLanguageCode": "ru"
    }
    
  3. Use the translate method to pass the file to be translated:

    $ export IAM_TOKEN=CggaATEVAgA...
    $ curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer ${IAM_TOKEN}" \
        -d @body.json \
        "https://translate.api.cloud.yandex.net/translate/v2/translate"
    

    The response from the service will contain translated text:

    {
        "translations": [
            {
            "text": "Привет",
            "detectedLanguageCode": "en"
            },
            {
            "text": "Мир",
            "detectedLanguageCode": "en"
            }
        ]
    }
    

Specify the source language

Sometimes words that are written identically in different languages, but are translated differently. For example, the word angel in English means a spiritual being, while in German it means a fishing rod. If the text you transmit contains words like this, SpeechKit may detect the source language incorrectly.

To avoid mistakes, specify the source language in the sourceLanguageCode field:

{
    "folder_id": "b1gvmob95yysaplct532",
    "texts": ["angel"],
    "targetLanguageCode": "ru",
    "sourceLanguageCode": "de"
}

Save the request body in a file (for example, body.json) and pass it using the translate method:

$ export IAM_TOKEN=CggaATEVAgA...
$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${IAM_TOKEN}" \
    -d @body.json \
    "https://translate.api.cloud.yandex.net/translate/v2/translate"

{
    "translations": [
        {
            "text": "удочка"
        }
    ]
}