Yandex Cloud
Search
Contact UsGet started
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML Services
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Start testing with double trial credits
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Center for Technologies and Society
    • Yandex Cloud Partner program
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
© 2025 Direct Cursus Technology L.L.C.
Yandex Translate
  • Getting started
    • All guides
    • How to translate text
    • How to improve the accuracy of translations
    • Detecting language
    • Getting a list of supported languages
    • Setting up access with API keys
  • Access management
  • Pricing policy
  • Audit Trails events

In this article:

  • Getting started
  • Translating a text from any language
  1. Step-by-step guides
  2. How to translate text

How to translate a text using Translate

Written by
Yandex Cloud
Updated at September 18, 2025
  • Getting started
  • Translating a text from any language

To translate text, use the translate method.

Getting startedGetting started

To authenticate under a service account, you can use an API key or an IAM token; to authenticate under a user account, you can only use an IAM token.

Get your account details for authentication in the Translate API:

API key
IAM token
  1. If you do not have a service account, create one.

  2. Assign the ai.translate.user role for the folder to the service account.

  3. Get the ID of the folder your service account was created in. Make sure to include the folder ID in the folderId field in the body of each request.

  4. Create an API key with the yc.ai.translate.execute scope.

    Provide the key in the Authorization header of each request in the following format:

    Authorization: Api-Key <API_key>
    
  1. Get the ID of any folder for which your account has the ai.translate.user role or higher. Make sure to include the folder ID in the folderId field in the body of each request.

  2. Get an IAM token for your Yandex account, federated account or service account.

    Provide the token in the Authorization header of each request in the following format:

    Authorization: Bearer <IAM_token>
    

Translating a text from any languageTranslating a text from any language

To translate a text from any supported language, provide it using the translate method:

cURL
Python
PHP

To use the examples, install cURL.

The example below is intended to be run in MacOS and Linux. To run it in Windows, see how to work with Bash in Microsoft Windows.

This example shows how to translate two strings containing Hello and World into Russian. The text source language is recognized automatically.

  1. Create a file with the request body, e.g., body.json:

    {
        "folderId": "<folder_ID>",
        "texts": ["Hello", "World"],
        "targetLanguageCode": "ru"
    }
    

    Where:

    • folderId: Folder ID you got before you started.
    • texts: Text to translate, as a list of strings.
    • targetLanguageCode: Target language. You can get the language code together with a list of supported languages.
  2. Submit the file for translation by running the command:

    export API_KEY=<API_key>
    curl \
      --request POST \
      --header "Content-Type: application/json" \
      --header "Authorization: Api-Key ${API_KEY}" \
      --data '@<path_to_JSON_file>' \
      "https://translate.api.cloud.yandex.net/translate/v2/translate"
    

    Where API_KEY is the API key you got before you started. If you use an IAM token for authentication, change the Authorization header to "Authorization: Bearer <IAM_token>".

    The service will return the translated strings:

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

This example shows how to translate the following two lines of text into Russian: Hello and World. The text source language is recognized automatically.

Create a file with the request body, e.g., body.py:

import requests

# Parameters for authentication with an API key as a service account:
API_KEY = "<API_key>"
# Parameters for authentication with an IAM token:
# IAM_TOKEN = '<IAM_token>'
folder_id = "<folder_ID>"
target_language = "ru"
texts = ["Hello", "World"]

body = {
    "targetLanguageCode": target_language,
    "texts": texts,
    "folderId": folder_id,
}

headers = {
    "Content-Type": "application/json",
    # Parameters for authentication with an API key as a service account:
    "Authorization": "Api-Key {0}".format(API_KEY),
    # Parameters for authentication with an IAM token:
    # "Authorization": "Bearer {0}".format(IAM_TOKEN)
}

response = requests.post(
    "https://translate.api.cloud.yandex.net/translate/v2/translate",
    json=body,
    headers=headers,
)

print(response.text)

Where:

  • Where API_KEY is the API key you got before you started. If you use an IAM token for authentication, change the Authorization header to "Authorization: Bearer <IAM_token>".

  • folder_id: Folder ID you got before you started.
  • target_language: Target language. You can get the language code together with a list of supported languages.
  • texts: Text to translate, as a list of strings.

You can save your API key to a file. In which case specify the file path in the key_path variable:

body.py
import os
import requests

# Parameters for authentication with an API key as a service account:
key_path = "<API_key_file_path>"
# Parameters for authentication with an IAM token:
# token_path = '<IAM_token_file_path>'
folder_id = "<folder_ID>"
target_language = "ru"
texts = ["Hello", "World"]

# Parameters for authentication with an API key as a service account:
API_KEY = os.path.join(os.getcwd(), key_path)
with open(API_KEY) as f:
    API_KEY = f.read().strip()
# Parameters for authentication with an IAM token:
# IAM_TOKEN = os.path.join(os.getcwd(), token_path)
# with open(IAM_TOKEN) as f:
#     IAM_TOKEN = f.read().strip()

body = {
    "targetLanguageCode": target_language,
    "texts": texts,
    "folderId": folder_id,
}

headers = {
    "Content-Type": "application/json",
    # Parameters for authentication with an API key as a service account:
    "Authorization": "Api-Key {0}".format(API_KEY),
    # Parameters for authentication with an IAM token:
    # "Authorization": "Bearer {0}".format(IAM_TOKEN)
}

response = requests.post(
    "https://translate.api.cloud.yandex.net/translate/v2/translate",
    json=body,
    headers=headers,
)

print(response.text)

This example shows how to translate the following two lines of text into Russian: Hello and World. The source language of a text is recognized automatically.

Create a file with the request body, e.g., body.php:

<?php

// Parameters for authentication with an API key as a service account:
$API_KEY = '<API_key>';
// Parameters for authentication with an IAM token:
// $IAM_TOKEN = '<IAM_token>';
$folder_id = '<folder_ID>';
$target_language = 'ru';
$texts = ["Hello", "World"];

$url = 'https://translate.api.cloud.yandex.net/translate/v2/translate';

$headers = [
    'Content-Type: application/json',
    // Parameters for authentication with an API key as a service account:
    "Authorization: Api-Key $API_KEY"
    // Parameters for authentication with an IAM token:
    // "Authorization: Bearer $IAM_TOKEN"
];

$post_data = [
    "targetLanguageCode" => $target_language,
    "texts" => $texts,
    "folderId" => $folder_id,
];

$data_json = json_encode($post_data);

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
// curl_setopt($curl, CURLOPT_VERBOSE, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_json);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, true);

$result = curl_exec($curl);

curl_close($curl);

var_dump($result);

?>

Where:

  • Where API_KEY is the API key you got before you started. If you use an IAM token for authentication, change the Authorization header to "Authorization: Bearer <IAM_token>".

  • folder_id: Folder ID you got before you started.
  • target_language: Target language. You can get the language code together with a list of supported languages.
  • texts: Text to translate as an array of strings.

You can save your API key to a file. In which case specify the file path in the key_path variable:

body.php
<?php

// Parameters for authentication with an API key as a service account:
$key_path = '<API_key_file_path>';
// Parameters for authentication with an IAM token:
// $token_path = '<IAM_token_file_path>';
$folder_id = '<folder_ID>';
$target_language = 'ru';
$texts = ["Hello", "World"];

$url = 'https://translate.api.cloud.yandex.net/translate/v2/translate';

// Parameters for authentication with an API key as a service account:
$API_KEY = trim(file_get_contents(realpath($key_path)));
// Parameters for authentication with an IAM token:
// $IAM_TOKEN = trim(file_get_contents(realpath($token_path)));

$headers = [
    'Content-Type: application/json',
    // Parameters for authentication with an API key as a service account:
    "Authorization: Api-Key $API_KEY"
    // Parameters for authentication with an IAM token:
    // "Authorization: Bearer $IAM_TOKEN"
];

$post_data = [
    "targetLanguageCode" => $target_language,
    "texts" => $texts,
    "folderId" => $folder_id,
];

$data_json = json_encode($post_data);

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
// curl_setopt($curl, CURLOPT_VERBOSE, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_json);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, true);

$result = curl_exec($curl);

curl_close($curl);

var_dump($result);

?>

What's nextWhat's next

  • How to increase translation accuracy

Was the article helpful?

Previous
All guides
Next
How to improve the accuracy of translations
© 2025 Direct Cursus Technology L.L.C.