Migrate to Advanced from Basic

Existing Cloud Translation - Basic (v2) users who want to use the latest Cloud Translation features, such as glossaries and AutoML models, must migrate their applications to use Cloud Translation - Advanced (v3). For a comparison, see Compare Basic and Advanced.

Migrating to the Advanced edition includes using Identity and Access Management (IAM) and the Advanced edition client libraries. The following sections outline migration tasks and the key differences between the two editions.

Migrating to Advanced

The following steps outline the actions required to update your existing applications from using Cloud Translation - Basic to Cloud Translation - Advanced.

1. Take inventory of your Google Cloud projects, applications, and users that access the Cloud Translation - Basic API. You will need to provide service accounts and update them to use the Cloud Translation - Advanced client libraries.
2. Set up service accounts and authentication for your application.
3. Use IAM roles to set permissions on service accounts.
4. Enable Cloud Translation - Advanced for your project. If you use AutoML models with the Cloud Translation - Advanced, you must enable AutoML as well. For more information, see the Setup guide
5. Use the Cloud Translation - Advanced client libraries and methods. For Cloud Translation - Advanced requests, you must include your project number (or project ID), and project location, such as global or us-central1.
6. Check that the size of your translation requests to Cloud Translation - Advanced do not exceed the limit.
7. Plan your translation request quota monitoring. Both versions of the API share the same daily and monthly quotas.
8. Review any potential changes in billing.

Key differences between Advanced and Basic

To help you understand your migration tasks, the following sections describe key differences between the Advanced and Basic editions.

Service accounts

For Cloud Translation - Basic, you can send authenticated requests by using API keys or service accounts.

Cloud Translation - Advanced has features that require customer-managed resources; these resources require IAM role and permissions management. Because of this, you cannot use API keys to authenticate to the service. Instead, you must use service accounts when authenticating to Cloud Translation - Advanced.

For more information, see the setup guide.

IAM roles

When you use service accounts for Cloud Translation - Basic, the service accounts are used for authentication only. You can make any calls to Cloud Translation - Basic no matter what permissions are associated with the service account. However, for Cloud Translation - Advanced, the permissions do apply.

To grant service accounts permissions to call Cloud Translation - Advanced, you assign IAM roles to them. Cloud Translation - Advanced has several IAM roles that you can assign to your service account to access specific resources in your project. For example, if you want to use your service account to translate text, you assign the roles/cloudtranslate.user role to it. For more information, see IAM roles in Cloud Translation - Advanced details.

If you plan to use AutoML models or any features that rely on Cloud Storage, you must also include the appropriate roles for those services. To view a list of all IAM roles, see the IAM roles documentation.

Translation models

When you request a translation by using Cloud Translation - Basic, Google uses a pre-trained Neural Machine Translation (NMT) model. For Cloud Translation - Advanced, you can use the pre-trained NMT model or an AutoML Translation custom model.

Service accounts that you use for translation requests must have the permissions to access the NMT and AutoML models, which can be located in different projects. For example, you might have a central project that contains your translation models to simplify maintenance and billing. Service accounts in that project or other projects can use those models but require permissions to do so.

For more information about translation models, see Translating text (Advanced).

Client libraries

The client libraries and methods for Cloud Translation - Advanced differ from Cloud Translation - Basic. For example, calls to Cloud Translation - Advanced require resource names. For more information, see the Cloud Translation - Advanced client libraries overview or try the translate text (advanced edition) quickstart.

Resources, projects, and locations

Requests to Cloud Translation - Advanced require the name of the resource that you want to use. A resource is typically a qualified name that includes the project name and its location, which specifies where the request is run. For example, the name of an AutoML model is a resource name.

If your Google Cloud project has the name my-project and the location for the resource is us-central1, then the full name of your resources might look like the following:

projects/MY_PROJECT/locations/us-central1/...

The URL that you send a getSupportedLanguages request might look like the following:

https://translation.googleapis.com/v3/projects/my-project/locations/us-central1/supportedLanguages

Note: All of your resources in a single request to Cloud Translation - Advanced must have the same location. Currently, only global and us-central1 locations are supported. For all custom resources—AutoML models, glossaries, long-running-operations—you must use us-central1. You can also use us-central1 when you use general translation models and language detection. You can only use the global location when you use general translation models and language detection.

Cloud Translation - Advanced also provides multi-regional endpoints, such as translate-eu.googleapis.com to keep data handling within the EU. This is a unique endpoint for EU and not a location setting on the global API. For more information, see Global and multi-regional endpoints.

Content limit per request

The Cloud Translation API is optimized for translating of smaller requests. The recommended maximum length for each request is 5K characters (code points). However, the more characters that you include, the higher the response latency. For Cloud Translation - Advanced, the maximum number of code points for a single request is 30K. Cloud Translation - Basic has a maximum request size of 100K bytes.

The Cloud Translation API rejects requests larger than the maximum and gives a 400 INVALID_ARGUMENT error regardless of the available quota.

For more information about quotas and limits, see Quotas.

What's next

Use Cloud Translation - Advanced to translate text, create glossaries, or make batch requests.