Hide
Translate API

Translate API Getting Started

Google Translate API is a paid service. For website translations, we encourage you to use the Google Website Translator gadget.

This document details the background knowledge that you need to use the Google Translate API v2.

Contents

  1. Introduction
  2. Learn about identifying your application
  3. Translate API background
    1. Translate concepts
    2. Translate API operations
  4. Calling style
    1. REST
  5. Data format
    1. JSON

Introduction

This document is intended for developers who want to write applications that can interact with the Google Translate API. Google Translate is a tool that automatically translates text from one language to another language (e.g. French to English). You can use the Google Translate API to programmatically translate text in your webpages or apps.

Setup

To get started using Google Translate API, you need to first create or select a project in the Google Developers Console and enable the API. Using this link guides you through the process and activates the Google Translate API automatically.

Alternatively, you can activate the Google Translate API yourself in the Developers Console by doing the following:

  1. Go to the Google Developers Console.
  2. Select a project, or create a new one.
  3. In the sidebar on the left, expand APIs & auth. Next, click APIs. Select the Enabled APIs link in the API section to see a list of all your enabled APIs. Make sure that the Google Translate API is on the list of enabled APIs. If you have not enabled it, select the API from the list of APIs, then select the Enable API button for the API.
  4. In the sidebar on the left, select Credentials.

In either case, you end up on the Credentials page and can create your project's credentials from here.

Important: Google Translate API v2 requires billing information for all accounts before you can start using the service. See instructions below on how to enable billing.

To enable billing for your project, do the following:

  1. Go to the project settings page. If prompted, select a project or create a new one.
  2. In the Billing section, click Enable billing.
  3. If you do not have a billing account, create one.
  4. Select your location, fill out the form, and click Submit and enable billing.

Learn about identifying your application

Every request your application sends to the Google Translate API must identify your application to Google, using an API key.

For information about how to use API keys, see Identifying your application to Google in the Using REST document.

Translate API background

Translate concepts

Google Translate is a tool that automatically translates text from one language to another language.

The source text is the text to be translated. The source language is the language that the source text is written in. The target language is language that the source text is translated into.

Translate API operations

There are three methods to invoke in the Google Translate API:

Operation Description REST HTTP mapping
translate Translates source text from source language to target language GET
languages List the source and target languages supported by the translate methods GET
detect Detect language of source text GET

Calling styles

There are several ways to invoke the API:

  • Using REST directly
  • Using REST from JavaScript (no server-side code required)

REST

REST, or Representational State Transfer, in the Google Translate API is somewhat different from traditional REST. Instead of providing access to resources, the API provides access to a service. As a result, the API provides a single URI that acts as the service endpoint.

You access the Google Translate API service endpoint using the GET REST HTTP verb, as described in API operations. You pass in the details of all service requests as query parameters.

Translate

The specific format for the single Google Translate API URI is:

https://www.googleapis.com/language/translate/v2?parameters

where parameters are any parameters to apply to the query. For details, see Working with results and Query parameter reference in the Using REST document.

Here is an example of how this works in the Translate API.

https://www.googleapis.com/language/translate/v2?key=INSERT-YOUR-KEY&q=hello%20world&source=en&target=de

Discover supported languages

The specific format to return the list of languages codes is:

https://www.googleapis.com/language/translate/v2/languages?parameters

where parameters are any parameters to apply to the query. For details, see Working with results and Query parameter reference in the Using REST document.

Here is an example of how languages method works in the Translate API.

https://www.googleapis.com/language/translate/v2/languages?key=INSERT-YOUR-KEY&target=zh-TW

Detect source language

The specific format to detect the language of a text is:

https://www.googleapis.com/language/translate/v2/detect?parameters

where parameters are any parameters to apply to the query. For details, see Working with results and Query parameter reference in the Using REST document.

Here is an example of how detect method works in the Translate API.

https://www.googleapis.com/language/translate/v2/detect?key=INSERT-YOUR-KEY&q=google+translate+is+fast

REST from JavaScript

You can invoke the Translate API using REST from JavaScript, using the callback query parameter and a callback function. However, be aware that your API key will be viewable in the HTML source for your page. By default a key can be used on any site. We strongly recommend that you restrict use of your key only to domains you administer, to prevent use on unauthorized sites.

You can specify which domains are allowed to use your API key by doing the following:

  1. Go to the Google Developers Console.
  2. Select a project.
  3. In the sidebar on the left, select APIs & auth, then select an API.
  4. On the API's info page, select the Quota link near the API name.
  5. In the sidebar on the left, select API Access.
  6. Click the Edit allowed referers link in the Simple API Access section of the page.

The following example uses this approach to translate some text and put it below the source text:

<html>
  <head>
    <title>Translate API Example</title>
  </head>
  <body>
    <div id="sourceText">Hello world</div>
    <div id="translation"></div>
    <script>
      function translateText(response) {
        document.getElementById("translation").innerHTML += "<br>" + response.data.translations[0].translatedText;
      }
    </script>
    <script>
      var newScript = document.createElement('script');
      newScript.type = 'text/javascript';
      var sourceText = escape(document.getElementById("sourceText").innerHTML);
      // WARNING: be aware that YOUR-API-KEY inside html is viewable by all your users.
      // Restrict your key to designated domains or use a proxy to hide your key
      // to avoid misuage by other party.
      var source = 'https://www.googleapis.com/language/translate/v2?key=YOUR-API-KEY&source=en&target=de&callback=translateText&q=' + sourceText;
      newScript.src = source;

      // When we add this script to the head, the request is sent off.
      document.getElementsByTagName('head')[0].appendChild(newScript);
    </script>
  </body>
</html>

Data format

JSON

JSON (JavaScript Object Notation) is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.