What is a translation API?
HTS is a web service that enables straightforward integration of Translated's translation service into your corporate workflow or content manager.
Your CMS calls HTS to get quotes and to place translation orders directly at our servers, exactly as a normal customer would do by clicking on our website Instant Quote widget. These translation orders will eventually be delivered back to your systems in an automatic, server-to-server fashion.
Key benefits of using HTS for your workflow are:
- Cost saving: immediate reduction of administrative and management costs.
- Speed: your text is translated and posted back to your website just a few hours after the order is placed.
- Robustness: an error-free process for managing multilingual content. No more copying and pasting!
- Agility: real-time quotation and delivery planning, no more back and forth with sales to get a quote.
You only pay for the translations you order. HTS has no setup cost and no monthly fees. Costs for human translation can be seen using our online quote. For more information, please contact us at hts@translated.com.
Getting started
This section describes the workflow. The HTS interaction is basically made of three steps:
- Quote
- Confirmation
- Delivery
Quote
You can get a translation quote issueing a request (GET and POST are both supported) at the following URL:
https://www.translated.net/hts/?f=quote&cid=htsdemo&p=htsdemo5&s=english&t=italian&w=1000&of=json
| Parameter | Description | Value |
|---|---|---|
| f | The "quote" function | quote |
| cid | Customer Username | htsdemo |
| p | Customer Password | htsdemo5 |
| s | Source language | english |
| t | Target language | japanese |
| text | Text to be translated | blob |
| df | The file format | |
| endpoint | Request delivery back at a public endpoint exposed on your side | http://www.yourdomain.com/translations/receive.php |
By this point, we have already retrieved your file, stored it on our systems, and initialized a project. This request actually hangs until we fetch the whole blob; the faster your internet link, the better.
Tip: if you have a slow internet link, consider uploading the file in advance somewhere and then passing us the URL to that file in the text parameter; see Function List for further details.
We also require you to specify the endpoint which your translated file will be delivered to. Please note that without an endpoint we will not be able to deliver the translation back to you.
Our system extracts plain text from your document and counts the words (if you didn’t explicitly provide the word count in the request via the w parameter).
A quote request response in json format looks like the following one:
{
"code": 1,
"message": "OK",
"delivery_date": "2019-04-03T16:30:00Z",
"words": 100,
"total": "9.50",
"pid": 23314595
}
| Value | Meaning |
|---|---|
| 1 | The request succeeded |
| OK | “OK” or an error message, if there was an error |
| 2013-09-26T15:30:00Z | Guaranteed delivery date in Zulu time (ISO 8601) |
| 3082 | The number of words as counted by us |
| 1216.99 | The price in Euro |
| 1040734 | The ID for this quote (projectID) |
Please note that the translation of your project has not started yet; we are just providing you with the following information:
- Cost
- Estimated delivery date and hour
- The total words counted by us
- A quote-unique identification number
To confirm the order, you have to issue a confirmation request.
See Function List for further details on the translaiton quote request.
Confirmation
Once you have reviewed and approved the translation quote API response, you can confirm it by passing back the following data:
https://www.translated.net/hts/?f=confirm&cid=YOUR-CUSTOMER-ID&p=YOUR-PASSWORD&pid=PROJECT-ID&c=CONFIRMATION-FLAG
Here's an example (both GET or POST methods are supported):
https://www.translated.net/hts/?f=confirm&cid=htsdemo&p=htsdemo5&pid=23304778&c=1&of=json
| Parameter | Description | Value |
|---|---|---|
| f | The "confirm" function | confirm |
| cid | Customer Username | htsdemo |
| p | Customer Password | htsdemo5 |
| pid | Project identifier | 23304778 |
| c | Confirmation flag | 1 |
Notice that the value of the pid parameter MUST be the same that you get in the response of a translation quote resquest.
If the confirmation is successful, you can expect the following response:
{
"code": 1,
"message": "OK"
}
| field | Value | Meaning |
|---|---|---|
| code | 1 | The request succeeded |
| messahe | OK | “OK” or an error message, if there was an error |
That’s it! The project has been confirmed and it’s been handed to one of our Project Managers, who will take care of selecting the best-matched translator for your file. From this point on, it's all easy sailing.
Delivery
Once we get the translated file from the professional translators, we carefully review it.
If it passes the quality check, the file is pushed back to an HTTP endpoint on your side which you previously agreed on with us (e.g.: http://www.your-domain.com/translations/receive.php)
The endpoint you provided should expect a POST at any time from us, with the following fields:
| Field | Description | Value |
|---|---|---|
| pid | Project identifier | 23304778 |
| t | Target language | japanese |
| text | Translated file | blob (base64 encoded) |
If you ordered multiple target languages, expect a separate request for each target language. The main difference between this process and a quote is that the quote is a “pull-oriented” function activated by you, while the delivery is a “push oriented” function triggered by us.
Here is a PHP example:
$pid = $_POST['pid'];
$t = $_POST['t'];
$text = base64_decode($_POST['text']);
// YOUR CODE TO STORE THE TRANSLATION HERE
// IF EVERYTHING WORKED FINE
$msg = "OK";
$code = 1;
echo implode("\n",array($code,$msg));
| Parameter | Description |
|---|---|
| Return Code | 1 if the quote has succeeded 0 if there was an error |
| Error Message | "OK" if there was no error, or else the error message The error message should be understandable and explain what went wrong. |
If you need a custom callback workflow, please contact us at hts@translated.com.
Testing environment
HTS comes with a sandbox environment for testing purposes, that lets us generate and send translation requests without actually creating a real order. The sandbox environment represents an accurate abstraction of the API procedure, and makes it possible to see the entire process in action, from the quote to delivery.
When confirming a project for which you previously requested a quote, all you have to do is add the sandbox=1 parameter in order to confirm that project as an API test, as follows:
https://www.translated.net/hts/?f=confirm&cid=htsdemo&p=htsdemo5&pid=23304778&c=1&sandbox=1&of=json
Please note that the quote function is identical for both testing and production.
Moreover, the text of the delivered message will not be the translation, but the same text you sent us with the quote, as the only purpose is to create a test translation project via API.
If there are multiple target languages in the quote, expect multiple deliveries in a random amount of time ranging between 30 seconds and 2 minutes.
Sandbox acts exactly the same as the real process, and lets you to test the entire loop for your integration.
Function List
Notice: mandatory parameters are shown in red.
Request a translation quote
This function returns the price and delivery date for a human translation. This is the first step to order a human translation via HTS API.
It requires at least the text or the w parameter to return a valid response.
That means that you can obtain a valid quote without actually sending your document if you provide at least the word count.
The quote function accepts the following parameters:
| Parameter | Description | Default | Example |
|---|---|---|---|
| cid | Username | cid=htsdemo | |
| p | Password | p=htsdemo5 | |
| s | Source language | s=English | |
| t | Target language(s). Comma separated values for multiple targets |
t=Italian t=Italian,Spanish,Japanese |
|
| text | The content to be translated. It can be an inline plain text or a URL pointing to the file. Please note that this is optional if the w parameter has been specified. |
text=Hello world text="https://www.translated.net/hts/HTS_Tech_Spec.pdf" |
|
| pn | Project name | HTS-NONAME | pn=Translation for tomorrow nr°2 |
| jt | Job Types: T for Professional R for Premium P for Economy |
T | jt=R |
| w | Number of words for this file. This parameter lets our server avoid computing the file's word count in real time, resulting in faster responses. |
w=5120 | |
| df | Data format, as the extension of the file. Necessary for automatic word counting. Automatic word counting is only available for: 'pdf', 'plaintext', 'txt', 'xml', 'html', 'htm', 'xliff', 'zip', 'rtf', 'doc','docx', 'aea'. Specify “zip” to send multiple zipped files; we’ll automatically guess the file format of the content. |
plaintext | df=zip |
| tm | A translation memory you wish to use for this project. The text parameter can be a file or a URL. Please note that you can also pass a MyMemory key. |
tm=823yuc908237 tm=http://www.yousite.net/hts/some_memory.tmx |
|
| endpoint | The url you want us to send the translation to. We suggest URL-encoding your endpoint in order to avoid parsing issues, especially when your link contains “&” or other special characters. |
endpoint=http://www.mysite.com/path/to/mypage.ext | |
| subject | The subject of the document you are sending. Check the List of supported subjects API method for a complete list. |
general | subject=accounting_finance |
| instructions | Specify a set of instructions for the translator, in plain text | instructions=please leave all lowercase; dates are in US format |
The quote function returns the following fields:
| Parameter | Description | Example |
|---|---|---|
| code | 1 if the quote has succeeded, 0 if there was an error | 1 |
| message | "OK" if there was no error, or else the error message | OK |
| delivery_date | The date and time representing the guaranteed deadline for the order, in ISO 8601 standard: YYYY-MM-DDTHH:mm:SSZ | 2013-02-18T12:32:00Z |
| words | Number of words given in the text parameter, either counted by us or submitted by the user with “w” parameter | 456 |
| total | Cost in Euro for the order, formatted as a number with no thousands separator and "." as decimal separator | 223.33 |
| pid | The project ID to be used when you want to confirm this order | 23304778 |
Sample HTTP Request and Response
GEThttps://www.translated.net/hts/?f=quote&cid=htsdemo&p=htsdemo5&s=english&t=japanese,italian&text=https://www.translated.net/hts/HTS_Tech_Spec.pdf&df=pdf&jt=P&pn=SimpleTest&w=300078&of=json
{
"code": 1,
"message": "OK",
"delivery_date": "2019-09-17T08:30:00Z",
"words": 300078,
"total": "24006.24",
"pid": 23318769
}
Place an order
This function confirms a previously requested human translation quote and place an actual order.
This is the second and final step in placing an order for human translation via HTS API.
The confirm function accepts the following parameters:
| Parameter | Description | Default | Example |
|---|---|---|---|
| cid | Username | cid=htsdemo | |
| p | Password | p=htsdemo5 | |
| pid | The project ID to be used when you want to confirm this order. | pid=23304778 | |
| c | Confirm flag. You confirm a quote inside the “confirm” function by assigning 1 to this parameter, and decline a quote by assigning 0. |
c=1 c=0e |
|
| sandbox | Sandbox mode. In this mode, the project is regarded as a test and the content to translate is sent to the endpoint as it is. No charges applied. | 0 | sandbox=1 |
| text | The content to be translated. It can be: an inline plain text/binary blob a URL pointing to the file |
text=Hello world text=https://www.translated.net/hts/HTS_Tech_Spec.pdf |
The confirm function returns the following fields:
| Parameter | Description | Example |
|---|---|---|
| code | 1 if the quote has succeeded, 0 if there was an error | 1 |
| message | "OK" if there was no error, or else the error message | OK |
Sample HTTP Request and Response
POSThttps://www.translated.net/hts/?f=confirm&cid=htsdemo&p=htsdemo5&c=1&pid=23304778&of=json
{
code: 1,
message: "OK"
}
Getting project status in real-time
This function lets you track the status of all the projects you have submitted.
The status function accepts following parameters:
| Parameter | Description | Default | Example |
|---|---|---|---|
| cid | Username | cid=htsdemo | |
| p | Password | p=htsdemo5 | |
| pid | The project ID to be used when you want to confirm this order. | pid=23304778 |
The status function returns the following fields:
| Parameter | Description | Example |
|---|---|---|
| code | 1 if the quote has succeeded, 0 if there was an error | 1 |
| message | "OK" if there was no error, or else the error message | OK |
| list of jobs belonging to the project | a job line consists of: id; job_type; source; target; words; customer_total; order_date; delivery_date; pm; pm_email |
9687796;REVISION;Italian;English;182;10.00;IN PROCESS;2012-11-29 T15:35:00Z;2013-01-25 T16:00:00Z;GIANFRANCO;gianfranco@translated.com |
Sample HTTP Request and Response
GEThttps://www.translated.net/hts/?f=status&cid=htsdemo&p=htsdemo5&c=1&pid=23304778&of=json
In the example below we have two jobs, for two different language combinations:
{
"0": {
"jid": "27742450",
"pid": "23304778",
"type": null,
"source": "English",
"target": "Japanese",
"words": "300078",
"price": "12003.12",
"status": "IN PROCESS",
"order_date": "2019-04-02T18:02:00Z",
"delivery_date": "2019-09-16T11:00:00Z",
"pm_name": "TEST",
"pm_email": "test@translated.com"
},
"1": {
"jid": "27742451",
"pid": "23304778",
"type": null,
"source": "English",
"target": "Italian",
"words": "300078",
"price": "12003.12",
"status": "IN PROCESS",
"order_date": "2019-04-02T18:02:13Z",
"delivery_date": "2019-09-16T11:00:00Z",
"pm_name": "TEST",
"pm_email": "test@translated.com"
},
"code": 1,
"message": "OK",
"count": 2
}
Utility Functions
List of supported languages
This function shows the list of language codes supported for human translation (for the source and target parameters of the quote and confirm functions). The list contains the RFC 3066 code and the ISO two and three letter codes.
This function should be used to periodically update the supported language list on your system
The ll function accepts following parameters:
| Parameter | Description | Default | Example |
|---|---|---|---|
| cid | Username | cid=htsdemo | |
| p | Password | p=htsdemo5 |
The ll function returns the following fields:
| Parameter | Description | Example |
|---|---|---|
| code | 1 if the quote has succeeded, 0 if there was an error | 1 |
| message | "OK" if there was no error, or else the error message | OK |
| list of languages | a language line consists of: language name; RFC3066 code; ISO 6391 code; ISO 6392 code |
Amharic;amAM;am;amh |
Sample HTTP Request and Response
GEThttps://www.translated.net/hts/?f=ll&cid=htsdemo&p=htsdemo5&of=json
{
code: 1,
message: "OK",
count: 183,
0: {
name: "Afrikaans",
rfc3066: "af-ZA",
iso6391: "af",
iso6392: "afr"
},
1: {
name: "Albanian",
rfc3066: "sq-AL",
iso6391: "sq",
iso6392: "alb"
},
...
}
List of supported subjects
This function shows the list of subject codes supported for human translation. This function should be used to periodically update the supported subjects list on your system.
The subjects function accepts following parameters:
| Parameter | Description | Default | Example |
|---|---|---|---|
| cid | Username | cid=htsdemo | |
| p | Password | p=htsdemo5 |
The subjects function returns the following fields:
| Parameter | Description | Example |
|---|---|---|
| code | 1 if the quote has succeeded, 0 if there was an error | 1 |
| message | "OK" if there was no error, or else the error message | OK |
| list of subjects | The subject of the document you want to translate | accounting_finance aerospace_defence architecture |
Sample HTTP Request and Response
GEThttps://www.translated.net/hts/?f=subjects&cid=htsdemo&p=htsdemo5&of=json
{
code: 1
message: "OK",
count: 40,
0: "accounting_finance",
1: "adwords",
2: "aerospace_defence",
...
}
FAQs
What is the expiration time of an unconfirmed quote placed via HTS?
A quote is valid for 24 hours.
What kind of files are supported?
We support any kind of file, since HTS is just a way to place orders and transfer files directly to our servers. However, advanced features like automatic word counting are available only for pdf, txt, xml, html, xliff, rtf, doc, docx, aea. For other formats, you should count the words yourself and then send us the exact amount of words via the specific parameter (see Quote function in the Function List).
How are translations delivered back? Email? FTP?
Documents are delivered via HTTP POST to a public endpoint of your choice. Please, remember to send us this information or we won’t be able to deliver your translations back to you.
What does the payment process look like?
We’ll send you an invoice for each project, with 5-days payment terms. For high volumes or regular usage we can arrange monthly payments.
Is the price the same for a plain text translation?
Yes, no price fluctuation. Please note that the more engineering we have to do to extract the text from the file, the higher the delay.
Why is the word count slightly different across different file formats for the same file?
The system automates word counting by parsing your file, extracting the pure text, and counting words. Richer file formats, like Word formats, may include additional metadata (file comments, author information, etc.) that nevertheless get extracted. This can cause minor fluctuations in the word count. Translated assures that a thorough inspection of each file is conducted by our Project Managers to ensure that no major word count discrepancy is present before starting the translation.
Can I still use the API if my file type is not available for automated word counting?
Yes. HTS supports any file type; the supported data formats are for the online automated word counting.
But I really want automated word counting for my file type!
Contact us at hts@translated.com and we’ll be happy to discuss it.
What if I want to translate the same source into multiple languages?
Send a list of comma separated values in the t parameter of the request, like this:
https://www.translated.net/hts/?f=quote&cid=htsdemo&p=htsdemo5&s=english&t=japanese,italian,spanish&text=blob&df=pdf&endpoint=http://www.your-domain.com/translations/receive&of=json
What if I just want to get a quote without actually sending the file?
Use the wordcount w parameter in place of text, like this:
https://www.translated.net/hts/?f=quote&cid=htsdemo&p=htsdemo5&s=english&t=japanese&w=1000&df=pdf&endpoint=http://www.your-domain.com/translations/receive&of=json
Is there any other output format for API responses?
Our HTS, by default, replies with pure text, however if you specify of=json it will return a JSON. This further optional parameter is supported by all of the API functions (quote, confirm, status, ll, subjects).
Is there a testing environment?
Our HTS offers a sandbox environment for checking the whole quoteconfirmdelivery loop, without making a real order. No charges will be applied for sandbox projects and there are no limits to the number of sandbox projects a user can make. Find a detailed explanation at the related section.