Best Practices

The following checklist contains practices critical for a healthy integration. Make sure your integration has all of them.

Follow the Gengo API workflow

The proper workflow is as follows:

  • Submit text for translation
  • Get order status
  • Retrieve completed translations

See the Visual Guide for more information.

Make use of triple brackets

Triple brackets are useful to make sure certain texts, such as brand names, are preserved and uncharged. Learn more

Note: HTML tags are an exception to this rule. Do not bracket them as you are not charged for them by default.

Make use of the position parameter

If you’re sending strings that are meant to be in a specific order (i.e., subtitles), use the position parameter (starting at 1) for each job in the request. This ensures that the translators sees your strings in the order they were meant to be seen/read.

Group jobs whenever possible

Set the as_group parameter to 1 when sending multiple jobs in the same language pair and level. This allows for better consistency as there’s only one translator working on these grouped jobs.

Provide context for translators

Providing additional context results to better translation quality and accuracy, and speeds up delivery.

Use the order-level comments for instructions, style guides, or links to external documents that provide additional context.

Use job-level comments to provide context for specific jobs. The attachments parameter allows you to send images for context. Learn more about the payloads here.

Store internal information in custom_data

The “custom_data” parameter is designed for users of our API to help connect information in your system for reference. Do not store reference information in the callback_url or slug.

Use both callback functionality AND update polling, not just one or the other

The callback/webhook functionality is used to receive notifications about the project and is an easy way to get updates when your orders change status. You can learn more about when these callbacks are sent on the callbacks page.

However, due to possible network issues, callbacks must not be relied upon entirely. Make sure to periodically poll for jobs to stay updated with your translations’ statuses. You can then the available translations using the GET /translate/jobs/{ids}/ endpoint as per the Visual Guide

Include the functionality to approve, reject, or return the jobs for corrections as necessary

Make sure to include the option to approve, reject, or return jobs for corrections using the PUT /translate/jobs/ endpoint.

See our section for review workflows for more information.

Unless you are working with trusted or preferred translators, it is best to use auto_approve = 0. By getting the job approved, you acknowledge that you are happy with the translation, and thus forfeit your right to refunds or request for retranslation.