Human Translation API

The Translate.com API allows you to easily integrate human translations into your digital service. With over 96 language combinations, our API will allow you to globalize your user base and expand your product into under-utilized markets. Below you can find all the documentation you need to get started!

To get started with our API...

Create an Account

About The API (Version 2.0)

The Translate.com Human Translation API is simple JSON REST API with JSON responses that allows external applications to order human translations for text content. Once that translation is complete, our server will call a post-back URL which will be specified in the Submit Human Translation Request Call. The post-back will contain the order ID as well as the translated text in the POST content. All POST parameters are required unless specified. Requests are limited to 150/minute per IP address.

Back to Top

Getting Started

Any translate.com user account can be used to access the API. To get started, simply make an account on translate.com then navigate to the Customer Portal in the upper right of the page. Once there, click the Account and API link on the left and generate an API Key.

Back to Top

Authentication

All API calls are authenticated via your unique API key. Instruction on how to find this are in the Getting Started Section. This API key will need to be submitted as a POST variable called "api_key" for each request.

Back to Top

Postbacks

If a postback_url POST parameter is submitted, we will call it once the human translation is done. The following POST variables will be sent in the postback: human_translation_id, order_number, source_text, source_language, translation_language, translated_text, completion_action

Back to Top

Error Codes

If an error is encountered when processing a call, "error_code" and "message" keys will be added to the output array. Here is what each error means.

Error Code Description
1000 Missing email_address
1001 Missing password
1002 Missing api_key
1003 Incorrect email address and/or password
1004 The API key was not was not recognized
1005 This IP address has hit our maximum requests per minute limit
2000 Missing source_language
2001 Missing source_text
2002 Missing translation_language
2003 Error processing order. See details given in response.
2004 Unable to determine the number of words in the text
2006 translation_language must be submitted as an array. Ie: translation_language[] = 'en'
2007 Missing presentation_gender
2008 Missing recipient_gender
2009 Missing topic_id . Topics can be viewed using the Get Human Translation Topics API Call
2010 Missing order_number.
2011 This order number can not be found or does not belong to this user.

Back to Top

Get Language Names

Returns our language codes and their respective names. Some languages are not available for human translations.

URL https://www.translate.com/api_v2/get_all_language_names
POST Parameters api_key (string)
Response result (boolean) - If the call was successful or not.
languages (array) - A key value array of the language codes and their names

Back to Top

Get Human Translation Language Combination

Returns an array of what human translation languages combinations are available.

URL https://www.translate.com/api_v2/get_all_human_translations_languages
POST Parameters api_key (string)
Response result (boolean) - If the call was successful or not.
languages (array) - A key value array of the language codes and their names

Back to Top

Get Human Translation Topics

Human translations can be submitted with an optional topic to give further instruction to the translators. This call shows the topics and their IDs.

URL https://www.translate.com/api_v2/get_human_translation_topics
POST Parameters api_key (string)
Response result (boolean) - If the call was successful or not.
topics (array) - A key value array of the topic ids and their titles.

Back to Top

Get Human Translation Cost

Gets a non-biding quote to get a human translation. The user can also their their plan in the order by submitting an optional "plan_id" POST parameter. When a plan is changed, if there are any un-used words left, the number or words are credited to the users account as rollover words. Rollover words expire at the end of each month. A customers credit card is not charged when placing an order until the user reaches $100.00 or more in charges. If the customer has a past balance of $95.00 and places a $10.00 human translation order, while the order is only $10.00, a payment of $105.00 will be required to process the order.

URL https://www.translate.com/api_v2/get_human_translation_cost
POST Parameters api_key (string)
source_language (string) - 2-6 character string of the language code.
source_text (text)
translation_languages (array) - The values are 2-6 character strings of the language code. An array is still required even if there is only one translation language code.
instructions_to_translators (optional string) This is a field for any special instructions to give to the translators. If special instructions are provided the Translation Memory will be bypassed.
Response result (boolean) - If the call was successful or not.
details (array) - This is an array describing the costs associated with the translation. The costs can be Initial Free Words given to each account, Rollover words, Plan words or an overage dollar amount.
details.translation_memory_words (int) - The number of words that are being fulfilled via your Translation Memory. These are no billed. details.initial_free_words (int) - The number of free human translation words the customer was given when they signed up.
details.free_words_remaining_before_order (int) - The number of free words were unused before the order.
details.free_words_used_in_order (int) - The number of free words used in this order.
details.free_words_used (int) - The number of free words that were used before the order.
details.free_words_remaining_after_order (int) - The number of free words the user has left after placing the order.
details.plan_changed (boolean) - If a plan_id was passed in, is it different than their current plan. Note: The ability to change a customers plan has not been released yet.
details.plan_change_cost (int) - The amount to be billed in this order for the new plan.
details.plan_id (int) - The ID of the new plan.
details.plan_name (string) - The name of the new plan.
details.plan_monthly_words_included (int) - The number of human translation words included each month with the plan.
details.plan_previous_plan_words_remaining_before_order (int) - The number of rollover words are remaining before placing the order.
details.plan_previous_plan_words_used (int) - The number of rollover words were used before placing the order.
details.plan_previous_plan_words_remaining_after_order (int) - The number of rollover words left after placing the order.
details.plan_monthly_words_remaining_before_order (int) - The number of plan words remaining before placing the order.
details.plan_monthly_words_used_in_order (int) - The number of monthly words used in the order
details.plan_monthly_words_used (int) - The number of monthly words used before starting the order.
details.plan_monthly_words_remaining_after_order (int) - The number of monthly words used after placing the order
details.languages (array) - An array of each translation language showing if a Translation Memory was used, how many free words were used, rollover words, plan words and overage costs were used.
details.translation_additional_cost (double) - The total dollar charge for this order
details.translation_additional_cost_words (int) - The number of words that are being charged a dollar amount for.
details.source_text_words (int) - How many words are in the text to translate.
details.order_words (int) - The number of words times the number of languages its being translated to.
details.total_order_cost (double) - The total dollar cost of this order.
details.previous_balance (double) - The customers previous dollar account balance.
details.charge_required (boolean) - Is a credit charge required to process this order.
details.charge_amount (int) - The amount of the required credit card charge.

Back to Top

Submit Human Translation Order

Submits a binding human translation order.

URL https://www.translate.com/api_v2/submit_human_translation_order
POST Parameters api_key (string)
source_language (string) - 2-6 character string of the language code.
source_text (text)
translation_languages (array) - The values are 2-6 character strings of the language code. An array is still required even if there is only one translation language code.
presentation_gender (string) - Valid values are "male", "female", "group", "neutral"
recipient_gender (string) - Valid values are "male", "female", "group", "neutral"
topic_id (int)
postback_url (optional string) - A publicly accessible URL that will will call once the translation is done, with the translation details in the POST array.
completion_action (optional string) - A value of "none" can be submitted if you do not want any notification when your order is done.
translator_notes (optional string) - Up to 255 characters that will be shown to translators to provide any specific instruction when translating the order.
Response result (boolean) - If the call was successful or not.
order_number (string)

Back to Top

Get Human Translation Text/Status

Gets the status or an order as well as the translated text once its completed.

URL https://www.translate.com/api_v2/get_human_translation_order
POST Parameters api_key (string)
order_number (string) - The order number returned from the Submit Human Translation Order API call.
Response result (boolean) - If the call was successful or not.
details (array) details.source_language_code (string) - The internal source language code.
details.source_language_name (string) - The name of the source language.
details.source_text (string) - Text to be translated.
details.translation_languages (array) - An array of all the translation languages and their status.
details.translation_languages.translation_language_code (string) - The internal translation language code.
details.translation_languages.translation_language_name (string) - The name of the translation language.
details.translation_languages.translated_text (string) - The completed translation text.
details.translation_languages.translation_status (string) - The status of the translation. Values are: 'pending_translation','pending_review','in_review','pending_translation_revision','pending_native_edit','in_native_edit','completed'.
details.date_submitted (string) - Date the order was submitted.
details.date_completed (string) - Date the order was completed. The value is NULL if the order is still in progress.

Back to Top