Google Translate API is a paid service . For website translations, we encourage you to use the Google Website Translator gadget .
This document describes how to use the common features of the Google Translate API v2 using the RESTful calling style.
- Introduction
- Identifying your application to Google
- Translate Text
- Discover Supported Languages
- Detect Language
Introduction
This document is intended for developers who want to write applications that can interact with the Google Translate API. With Google Translate , you can programmatically translate text in your webpages or apps.
If you're unfamiliar with Google Translate concepts, you should read Getting Started before starting to code.
The result of a request to the Translate API is a simple JSON object.
Identifying your application to Google
To find your project's API key, follow these steps:
- Go to the Google Developers Console .
- Select a project.
- In the sidebar on the left, select APIs & auth . In the list of APIs, make sure the status is ON for the Google Translate API.
- In the sidebar on the left, select Credentials .
-
The API supports two types of credentials. Create whichever credentials are appropriate for your project:
-
OAuth 2.0: Your application must send an OAuth 2.0 token with any request that accesses private user data. Your application sends a client ID and, possibly, a client secret to obtain a token. You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications.
Note: Since this API does not have any methods that require OAuth 2.0 authorization, you might only need to obtain public API keys , which are described in the next list item. However, you still need OAuth 2.0 credentials if your application calls other APIs that require user authorization. The OAuth 2.0 documentation explains how to use your credentials to authorize API requests.
-
Public API keys: A request that does not provide an OAuth 2.0 token must send an API key. The key identifies your project and provides API access, quota, and reports. If the key type you need does not already exist, create an API key by selecting Create New Key and then selecting the appropriate key type. Then enter the additional data required for that key type.
-
If you believe that your key has been compromised—for instance, if you notice suspicious activity in your Console traffic reports—then Google recommends generating a new key by clicking the "Generate new key" button to the right of the key. Upon doing this, you can decide whether or not to allow up to 24 hours to phase out your old key, during which time both keys are active. Using a phased deactivation gives you time to fully deploy your new key. If, instead, you want to invalidate the old key immediately, then click the "Delete key" button to the right of the key.
Translate Text
Working with results
You can translate text from one language to another language by sending an HTTP
GET
request to its URI. The URI for a request has the following format:
https://www.googleapis.com/language/translate/v2?parameters
Three query parameters are required with each translation request:
- API key
- Use the key query parameter to identify your application.
- Target language
- Use the target query parameter to specify the language you want to translate into.
- Source text string
- Use the q query parameter to identify the string to translate.
All other
query parameters
are optional. The URL for the
GET
, including parameters, must be less than 2K characters.
Note:
You can also use
POST
to invoke the API if you want to send more data in a single request. The
q
parameter in the
POST
body must be less than 5K characters. To use
POST
, you must use the
X-HTTP-Method-Override
header to tell the Translate API to treat the request as a
GET
(use
X-HTTP-Method-Override: GET
).
Here is an example that specifies the source language, using the
source
query parameter:
GET https://www.googleapis.com/language/translate/v2?key=INSERT-YOUR-KEY&source=en&target=de&q=Hello%20world
If the request succeeds, the server responds with a
200 OK
HTTP status code and the data properties:
JSON
200 OK
{
"data": {
"translations": [
{
"translatedText": "Hallo Welt"
}
]
}
}
In this example, the response is simply the 'translatedText' field, with the translation.
Here is an another example passing multiple source texts to translate:
GET https://www.googleapis.com/language/translate/v2?key=INSERT-YOUR-KEY&source=en&target=de&q=Hello%20world&q=My%20name%20is%20Jeff
If the request succeeds, the server responds with a
200 OK
HTTP
status code and the data properties:
JSON
200 OK
{
"data": {
"translations": [
{
"translatedText": "Hallo Welt"
},
{
"translatedText": "Mein Name ist Jeff"
}
]
}
}
Here, 'translations' is an array of objects with 'translatedText', each of which is the translation of a query in the order the user provided.
Here is an another example in which the language of the source text is auto-detected:
GET https://www.googleapis.com/language/translate/v2?key=INSERT-YOUR-KEY&target=de&q;=Hello%20world
If the request succeeds, the server responds with a
200 OK
HTTP status code and the data properties:
JSON
200 OK
{
"data": {
"translations": [
{
"translatedText": "Hallo Welt",
"detectedSourceLanguage": "en"
}
]
}
}
Just as in the example above, 'translations' is an array of objects with 'translatedText' and the translation of the query. 'detectedSourceLanguage' is a language code as defined in the 'Language reference' section below. Note that other languages not listed below may be returned. They will be iso639-1 language codes.
Query parameter reference
The query parameters you can use with the Translate API are summarized in the following table. All parameter values need to be URL encoded.
| Parameter | Meaning | Notes |
|---|---|---|
callback
|
A JavaScript function to run when the response is received |
|
format
|
Format |
|
key
|
Your API key |
|
prettyprint
|
Returns a response with indentations and line breaks |
|
q
|
Source text |
|
source
|
Source language |
|
target
|
Target language |
|
Language reference
Translations between the languages listed in the following table are supported:
| Language | Language code |
|---|---|
| Afrikaans |
af
|
| Albanian |
sq
|
| Arabic |
ar
|
| Azerbaijani |
az
|
| Basque |
eu
|
| Bengali |
bn
|
| Belarusian |
be
|
| Bulgarian |
bg
|
| Catalan |
ca
|
| Chinese Simplified |
zh-CN
|
| Chinese Traditional |
zh-TW
|
| Croatian |
hr
|
| Czech |
cs
|
| Danish |
da
|
| Dutch |
nl
|
| English |
en
|
| Esperanto |
eo
|
| Estonian |
et
|
| Filipino |
tl
|
| Finnish |
fi
|
| French |
fr
|
| Galician |
gl
|
| Georgian |
ka
|
| German |
de
|
| Greek |
el
|
| Gujarati |
gu
|
| Haitian Creole |
ht
|
| Hebrew |
iw
|
| Hindi |
hi
|
| Hungarian |
hu
|
| Icelandic |
is
|
| Indonesian |
id
|
| Irish |
ga
|
| Italian |
it
|
| Japanese |
ja
|
| Kannada |
kn
|
| Korean |
ko
|
| Latin |
la
|
| Latvian |
lv
|
| Lithuanian |
lt
|
| Macedonian |
mk
|
| Malay |
ms
|
| Maltese |
mt
|
| Norwegian |
no
|
| Persian |
fa
|
| Polish |
pl
|
| Portuguese |
pt
|
| Romanian |
ro
|
| Russian |
ru
|
| Serbian |
sr
|
| Slovak |
sk
|
| Slovenian |
sl
|
| Spanish |
es
|
| Swahili |
sw
|
| Swedish |
sv
|
| Tamil |
ta
|
| Telugu |
te
|
| Thai |
th
|
| Turkish |
tr
|
| Ukrainian |
uk
|
| Urdu |
ur
|
| Vietnamese |
vi
|
| Welsh |
cy
|
| Yiddish |
yi
|
Discover Supported Languages
Working with results
You can discover the supported languages of this API by sending an HTTP
GET
request to its URI. The URI for a request has the following format:
https://www.googleapis.com/language/translate/v2/languages?parameters
One query parameter is required with each request:
- API key
- Use the key query parameter to identify your application.
All other query parameters are optional.
Here is an example to get back a list of language codes which supported by translate API:
GET https://www.googleapis.com/language/translate/v2/languages?key=INSERT-YOUR-KEY
If the request succeeds, the server responds with a
200 OK
HTTP status code and the data properties:
JSON
200 OK
{
"data": {
"languages": [
{
"language": "en"
},
{
"language": "fr"
},
...
{
"language": "zh-CN"
}
]
}
}
This query returns iso639-1 language codes for supported languages for translation. Some language codes also include a country code, like zh-CN or zh-TW. The list is sorted alphabetically by language code.
Here is another example that returns the list of supported languages in a given target language. The returned list is sorted alphabetically according to that target language.
GET https://www.googleapis.com/language/translate/v2/languages?key=INSERT-YOUR-KEY&target=zh-TW
If the request succeeds, the server responds with a
200 OK
HTTP status code and the data properties:
JSON
200 OK
{
"data": {
"languages": [
{
"language": "zh-CN",
"name": "中文(簡體)"
},
{
"language": "fr",
"name": "法文"
},
...
{
"language": "en",
"name": "英文"
}
]
}
}
In this case, the query returns the same language codes as above, plus a string 'name' of the name of the language written in the language suggested.
Query parameter reference
The query parameters you can use with the API are summarized in the following table. All parameter values need to be URL encoded.
| Parameter | Meaning | Notes |
|---|---|---|
callback
|
A JavaScript function to run when the response is received |
|
key
|
Your API key |
|
prettyprint
|
Returns a response with indentations and line breaks |
|
target
|
Target language |
|
Detect Language
Working with results
You can detect the language of a text string by sending an HTTP
GET
request to its URI. The URI for a request has the following format:
https://www.googleapis.com/language/translate/v2/detect?parameters
Two query parameters are required with each translation request:
- API key
- Use the key query parameter to identify your application.
- Source text string
- Use the q query parameter to identify the string to translate.
All other
query parameters
are optional. The URL for the
GET
, including parameters, must be less than 2K characters.
Note:
You can also use
POST
to invoke the API if you want to send more data in a single request. The
q
parameter in the
POST
body must be less than 5K characters. To use
POST
, you must use the
X-HTTP-Method-Override
header to tell the Translate API to treat the request as a
GET
(use
X-HTTP-Method-Override: GET
).
Here is an example that specifies the text to be "Google Translate Rocks", using the
q
query parameter:
GET https://www.googleapis.com/language/translate/v2/detect?key=INSERT-YOUR-KEY&q=Google%20Translate%20Rocks
If the request succeeds, the server responds with a
200 OK
HTTP status code and the data properties:
JSON
200 OK
{
"data": {
"detections": [
[
{
"language": "en",
"isReliable": false,
"confidence": 0.18397073
}
]
]
}
}
In this example, 'language' is the language code in the same format as described in the examples above. 'isReliable' has been DEPRECATED. This was an optional parameter that may have been returned when we had a signal of whether the detection was reliable or not. In reality, this was not a very reliable parameter, so we plan to remove this in the near future. 'confidence' is an optional parameter with a floating point value between 0 and 1. The closer this value is to 1, the higher the confidence in language detection. Note that this parameter is not always available.
Here is another example that passes multiple source text strings to language-detect:
GET https://www.googleapis.com/language/translate/v2/detect?key=INSERT-YOUR-KEY&q;=Hello%20world&q;=%E6%88%91%E5%A7%93%E8%AD%9A
If the request succeeds, the server responds with a
200 OK
HTTP status code and the data properties:
JSON
200 OK
{
"data": {
"detections": [
[
{
"language": "en",
"isReliable": false,
"confidence": 0.114892714
}
]
]
},
"data": {
"detections": [
[
{
"language": "zh-TW",
"isReliable": false,
"confidence": 0.7392313
}
]
]
}
}
Here, 'language' and 'confidence' are just as described in an earlier example but with repeated 'data' fields due to having multiple source text strings in the request. 'isReliable' has been deprecated, as explained above.
Query parameter reference
The query parameters you can use with the Detect Language API are summarized in the following table. All parameter values need to be URL encoded.
| Parameter | Meaning | Notes |
|---|---|---|
callback
|
A JavaScript function to run when the response is received |
|
key
|
Your API key |
|
prettyprint
|
Returns a response with indentations and line breaks |
|
q
|
Source text |
|