Premium Edition

The Google Cloud Translation API uses a standard edition model for most translation tasks. Google recently augmented its translation service to use a more robust Neural Machine Translation System. Users of the Cloud Translation API can now use this system for their own purposes, provided they:

  • Request access to this Beta feature and get their project approved
  • Adjust their code to request a Neural Machine Translation (NMT) model.
  • Understand that use of the Premium Edition uses a different pricing scheme, which will be detailed when your project is approved for access.

This guide provides information on how to request access and perform requests using the Premium edition.

Access to the Google Cloud Translation API Premium Edition is available to customers on a case-by-case basis only. This is a Beta feature of the Google Cloud Translation API. This feature might be altered or changed in the future, and is not subject to any SLA or deprecation policy. This feature is not intended for real-time usage in critical applications.

Access to the Premium Edition

Developers wishing to access this translation service through the Cloud Translation API can now do so, by requesting access from the Cloud Translation API Premium Edition Beta Sign Up Form Once your project is approved, you can begin using the premium edition using the instructions found in this guide.

The Google Cloud Translation API Premium edition supports the following language pairs for translation:

Language Pair Language Codes
German <-> English de <-> en
Spanish <-> English es <-> en
French <-> English fr <-> en
Japanese <-> English ja <-> en
Korean <-> English ko <-> en
Portuguese <-> English pt <-> en
Turkish <-> English tr <-> en
Chinese(Simplified) <-> English zh-CN* <-> en

* Simplified Chinese may be specified either by zh-CN or zh. Traditional Chinese (zh-TW) is not yet supported.

Additional language pairs will be added in the future and this page will be updated to reflect those revisions.

Using the Premium Edition

To direct the Google Cloud Translation API to use its premium edition, instead of its standard edition, pass a model parameter set to nmt within the request.

The model parameter is a string that currently supports the following values:

  • base (default) uses the standard edition
  • nmt uses the premium edition using a Neural Machine Translation model

Additional editions may be added in the future.

You may pass this model parameter either as a GET query parameter, or as a field within a JSON POST request.

Due to a known issue, GET requests that pass a model parameter for projects that have not yet been approved for use of the premium edition will error; POST requests will silently switch to use the standard edition and succeed.

An example using the Premium Edition

We'll show an example translating the following text from John F. Kennedy's inaugural address from English into German:

So let us begin anew--remembering on both sides that civility is not a sign of
weakness, and sincerity is always subject to proof. Let us never negotiate out
of fear. But let us never fear to negotiate.

To use the premium edition, first make sure you have set up your project to use the Translation API:

  • Set up your project and the Cloud Translation API as shown in the Quickstart.

  • Authenticate to your service account, passing the location of your service account key file:

    gcloud auth activate-service-account --key-file=<var>service-account-key-file</var>

  • Obtain an authorizaton token using your service account:

    gcloud auth print-access-token

Then construct a GET or POST request using this authorization token as shown below.

Sending a GET request

To perform a GET request using the Premium edition:

  • Use curl to make a v2 request, passing it the access token you printed, the text to translate (using URL encoding), the target language, and a model parameter set to nmt:

    $ curl -s -k -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access_token'
      'https://translation.googleapis.com/language/translate/v2?q=So%20let%20us%20begin%20anew--remembering%20on%20both%20sides%20that%20civility%20is%20not%20a%20sign%20of%20weakness%2C%20and%20sincerity%20is%20always%20subject%20to%20proof.%20Let%20us%20never%20negotiate%20out%20of%20fear.%20But%20let%20us%20never%20fear%20to%20negotiate.&target=de&model=nmt'
    

Sending a POST request

To perform a JSON POST request using the Premium edition:

  • Construct a JSON request of the following form, making sure to specify model using nmt:

    {
      'q': 'So let us begin anew--remembering on both sides that civility is not a
        sign of weakness, and sincerity is always subject to proof. Let us never
        negotiate out of fear. But let us never fear to negotiate.',
      'target': 'de',
      'model': 'nmt',
    }
    

Comparing results

Using the standard edition produces the following result within the response's translations field:

"translatedText": "Lassen Sie uns also neu beginnen - auf beiden Seiten nicht
                   vergessen, dass Zivilität ist kein Zeichen von Schwäche, und
                   Aufrichtigkeit ist immer unter Beweis. Lassen Sie uns nie aus
                   Angst verhandeln. Aber lassen Sie uns nie zu verhandeln
                   fürchten.",

The premium edition produces this result within the response's translations field:

"translatedText": "Fangen wir also von neuem an - auf beiden Seiten erinnern wir
                   uns, daß die Höflichkeit kein Zeichen der Schwäche ist und
                   die Aufrichtigkeit immer unter Beweis gestellt wird. Lasst
                   uns nie aus Furcht verhandeln. Aber lassen Sie uns niemals
                   Angst haben, zu verhandeln.",
"detectedSourceLanguage": "en",
"model": "nmt"

Note that when successfully using the premium edition, the response includes the model nmt within the response.

Sample Code

The following sample shows how to use the model parameter within client library code.

Node.js

For more on installing and creating a Cloud Translation API client, refer to Cloud Translation API Client Libraries.

function translateTextWithModel (input, target, model) {
  // The text to translate, e.g.:
  // input = 'Hello, world';
  // The target language, e.g.:
  // target = 'ru';
  // The model to use, e.g.:
  // model = 'nmt';

  if (!Array.isArray(input)) {
    input = [input];
  }

  // Instantiates a client
  const translate = Translate();

  const options = {
    // The target language, e.g. "ru"
    to: target,
    // Make sure your project is whitelisted.
    // Possible values are "base" and "nmt"
    model: model
  };

  // Translates the text into the target language. "input" can be a string for
  // translating a single piece of text, or an array of strings for translating
  // multiple texts.
  return translate.translate(input, options)
    .then((results) => {
      let translations = results[0];
      translations = Array.isArray(translations) ? translations : [translations];

      console.log('Translations:');
      translations.forEach((translation, i) => {
        console.log(`${input[i]} => (${target}) ${translation}`);
      });

      return translations;
    });
}

Python

For more on installing and creating a Cloud Translation API client, refer to Cloud Translation API Client Libraries.

def translate_text_with_model(target, text, model=translate.NMT):
    """Translates text into the target language.

    Make sure your project is whitelisted.

    Target must be an ISO 639-1 language code.
    See https://g.co/cloud/translate/v2/translate-reference#supported_languages
    """
    translate_client = translate.Client()

    # Text can also be a sequence of strings, in which case this method
    # will return a sequence of results for each text.
    result = translate_client.translate(
        text,
        target_language=target,
        model=model)

    print(u'Text: {}'.format(result['input']))
    print(u'Translation: {}'.format(result['translatedText']))
    print(u'Detected source language: {}'.format(
        result['detectedSourceLanguage']))

Java

For more on installing and creating a Cloud Translation API client, refer to Cloud Translation API Client Libraries.

public static void translateTextWithOptionsAndModel(
    String sourceText,
    String sourceLang,
    String targetLang,
    PrintStream out) {

  Translate translate = createTranslateService();
  TranslateOption srcLang = TranslateOption.sourceLanguage(sourceLang);
  TranslateOption tgtLang = TranslateOption.targetLanguage(targetLang);

  // Use translate `model` parameter with `base` and `nmt` options.
  TranslateOption model = TranslateOption.model("nmt");

  Translation translation = translate.translate(sourceText, srcLang, tgtLang, model);
  out.printf("Source Text:\n\tLang: %s, Text: %s\n", sourceLang, sourceText);
  out.printf("TranslatedText:\n\tLang: %s, Text: %s\n", targetLang,
      translation.getTranslatedText());
}

Ruby

For more on installing and creating a Cloud Translation API client, refer to Cloud Translation API Client Libraries.

# project_id    = "Your Google Cloud project ID"
# text          = "The text you would like to translate"
# language_code = "The ISO 639-1 code of language to translate to, eg. 'en'"

require "google/cloud/translate"

translate   = Google::Cloud::Translate.new project: project_id
translation = translate.translate text, to: language_code, model: "nmt"

puts "Translated '#{text}' to '#{translation.text.inspect}'"
puts "Original language: #{translation.from} translated to: #{translation.to}"

Send feedback about...

Translation API