{"_id":"54afb7180cf42a0b001d5bf4","project":"54ad6c769219922100751763","title":"Getting Started","type":"basic","excerpt":"","hidden":false,"githubsync":"","sync_unique":"","__v":37,"body":"The Unbabel API allows you to automatically translate large volumes of content, with human quality, between more than 50 language pairs. This high scalability is achieved by our community of more than 40K translators, empowered with Unbabel's Artificial Intelligence technology.\n\nThe following diagram illustrates Unbabel's translation process:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/KeDKiKJIReCC93tsLWQI_unbabel_api_diagram_20151214.png\",\n        \"unbabel_api_diagram_20151214.png\",\n        \"1447\",\n        \"926\",\n        \"#49aaa4\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nIt's important to understand that each translation request involves human processing. For this reason, all responses are asynchronous.\n[block:api-header]\n{\n  \"title\": \"Brand\"\n}\n[/block]\nAt Unbabel we know that some customers need to **manage multiple brands** (or products and services), so we’ve made it easy to manage these under one Unbabel account.\n\nAll Unbabel accounts will now have a default **Brand**, with the ability to add more. Each Brand can have its own Tones, Instructions and Glossaries on a **per language** basis.\n\nIf you have multiple Brands and request a translation without specifying which one to use, then we will use the default Brand, so please make sure you select the correct one.\n\n**PLEASE NOTE:** Currently, Brands can only be configured by our Customer Success team. Please email them at **[customer.success@unbabel.com](mailto:customer.success@unbabel.com)** for more information.ore information.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Tone, Topics and Translation Instructions\"\n}\n[/block]\nTo help Unbabel Editors translate your content in the best possible way, each translation request should have as much context as possible. This context is set by filling-in the following fields of each request:\n\n* **tone** that Unbabel Editors should take into account when working on the translation, you can select one of the following: \"Informal\", \"Formal\"\n\n* **topics** to help Unbabel choose the more appropriate Editors for your type of content, examples are \"travel\", \"technology\" or \"sports\" \n\n* **instructions** to be shown to Editors while they are working on your translation, examples are \"This is a product description for an e-commerce website\", \"This is a customer support ticket for a travel website\" or \"Please open www.example.com for reference\"\n\n**It's very important** that you provide as much of this information as possible on each translation request.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Glossary and Style Guide\"\n}\n[/block]\nAre there any terms, like brands or product features, that should not be translated? Should the communication be formal or informal? For this reason, each Unbabel account has associated one or more **Brands**, where at least one of them will be checked as default and each brand has Glossary.\n\nDepending on your type of content, our Customer Success Team may ask you for sample content or references that can be used to speed up the creation of the Glossary and Style Guide.\n\nPlease note that **translation requests done before this onboarding process** may result in the wrong translation of brand or product terms. Our team at **[customer.success@unbabel.com](mailto:customer.success@unbabel.com)** will help on this process.","link_external":false,"link_url":"","parentDoc":null,"slug":"getting-integrated","updates":[],"user":"54ad6c239219922100751762","category":"54afb7170cf42a0b001d5bf1","order":0,"version":"54afb7160cf42a0b001d5bf0","api":{"params":[],"results":{"codes":[]},"settings":"","url":"","auth":"required"},"createdAt":"2015-01-07T17:27:19.700Z","isReference":false,"next":{"description":"","pages":[]},"childrenPages":[]}

Getting Started


The Unbabel API allows you to automatically translate large volumes of content, with human quality, between more than 50 language pairs. This high scalability is achieved by our community of more than 40K translators, empowered with Unbabel's Artificial Intelligence technology. The following diagram illustrates Unbabel's translation process: [block:image] { "images": [ { "image": [ "https://files.readme.io/KeDKiKJIReCC93tsLWQI_unbabel_api_diagram_20151214.png", "unbabel_api_diagram_20151214.png", "1447", "926", "#49aaa4", "" ] } ] } [/block] It's important to understand that each translation request involves human processing. For this reason, all responses are asynchronous. [block:api-header] { "title": "Brand" } [/block] At Unbabel we know that some customers need to **manage multiple brands** (or products and services), so we’ve made it easy to manage these under one Unbabel account. All Unbabel accounts will now have a default **Brand**, with the ability to add more. Each Brand can have its own Tones, Instructions and Glossaries on a **per language** basis. If you have multiple Brands and request a translation without specifying which one to use, then we will use the default Brand, so please make sure you select the correct one. **PLEASE NOTE:** Currently, Brands can only be configured by our Customer Success team. Please email them at **[customer.success@unbabel.com](mailto:customer.success@unbabel.com)** for more information.ore information. [block:api-header] { "type": "basic", "title": "Tone, Topics and Translation Instructions" } [/block] To help Unbabel Editors translate your content in the best possible way, each translation request should have as much context as possible. This context is set by filling-in the following fields of each request: * **tone** that Unbabel Editors should take into account when working on the translation, you can select one of the following: "Informal", "Formal" * **topics** to help Unbabel choose the more appropriate Editors for your type of content, examples are "travel", "technology" or "sports" * **instructions** to be shown to Editors while they are working on your translation, examples are "This is a product description for an e-commerce website", "This is a customer support ticket for a travel website" or "Please open www.example.com for reference" **It's very important** that you provide as much of this information as possible on each translation request. [block:api-header] { "type": "basic", "title": "Glossary and Style Guide" } [/block] Are there any terms, like brands or product features, that should not be translated? Should the communication be formal or informal? For this reason, each Unbabel account has associated one or more **Brands**, where at least one of them will be checked as default and each brand has Glossary. Depending on your type of content, our Customer Success Team may ask you for sample content or references that can be used to speed up the creation of the Glossary and Style Guide. Please note that **translation requests done before this onboarding process** may result in the wrong translation of brand or product terms. Our team at **[customer.success@unbabel.com](mailto:customer.success@unbabel.com)** will help on this process.
The Unbabel API allows you to automatically translate large volumes of content, with human quality, between more than 50 language pairs. This high scalability is achieved by our community of more than 40K translators, empowered with Unbabel's Artificial Intelligence technology. The following diagram illustrates Unbabel's translation process: [block:image] { "images": [ { "image": [ "https://files.readme.io/KeDKiKJIReCC93tsLWQI_unbabel_api_diagram_20151214.png", "unbabel_api_diagram_20151214.png", "1447", "926", "#49aaa4", "" ] } ] } [/block] It's important to understand that each translation request involves human processing. For this reason, all responses are asynchronous. [block:api-header] { "title": "Brand" } [/block] At Unbabel we know that some customers need to **manage multiple brands** (or products and services), so we’ve made it easy to manage these under one Unbabel account. All Unbabel accounts will now have a default **Brand**, with the ability to add more. Each Brand can have its own Tones, Instructions and Glossaries on a **per language** basis. If you have multiple Brands and request a translation without specifying which one to use, then we will use the default Brand, so please make sure you select the correct one. **PLEASE NOTE:** Currently, Brands can only be configured by our Customer Success team. Please email them at **[customer.success@unbabel.com](mailto:customer.success@unbabel.com)** for more information.ore information. [block:api-header] { "type": "basic", "title": "Tone, Topics and Translation Instructions" } [/block] To help Unbabel Editors translate your content in the best possible way, each translation request should have as much context as possible. This context is set by filling-in the following fields of each request: * **tone** that Unbabel Editors should take into account when working on the translation, you can select one of the following: "Informal", "Formal" * **topics** to help Unbabel choose the more appropriate Editors for your type of content, examples are "travel", "technology" or "sports" * **instructions** to be shown to Editors while they are working on your translation, examples are "This is a product description for an e-commerce website", "This is a customer support ticket for a travel website" or "Please open www.example.com for reference" **It's very important** that you provide as much of this information as possible on each translation request. [block:api-header] { "type": "basic", "title": "Glossary and Style Guide" } [/block] Are there any terms, like brands or product features, that should not be translated? Should the communication be formal or informal? For this reason, each Unbabel account has associated one or more **Brands**, where at least one of them will be checked as default and each brand has Glossary. Depending on your type of content, our Customer Success Team may ask you for sample content or references that can be used to speed up the creation of the Glossary and Style Guide. Please note that **translation requests done before this onboarding process** may result in the wrong translation of brand or product terms. Our team at **[customer.success@unbabel.com](mailto:customer.success@unbabel.com)** will help on this process.
{"_id":"566ed43e95fe82170035ed6d","createdAt":"2015-12-14T14:37:50.599Z","project":"54ad6c769219922100751763","slug":"2-use-cases","sync_unique":"","title":"Use Cases","user":"5669472c08f90021008e887d","api":{"auth":"required","params":[],"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"githubsync":"","order":1,"excerpt":"","hidden":false,"link_external":false,"parentDoc":null,"version":"54afb7160cf42a0b001d5bf0","__v":15,"body":"The following table summarises common use cases of the Unbabel API and the corresponding formats that should be set on the `text_format` field.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Use Case\",\n    \"h-1\": \"Format\",\n    \"0-0\": \"Product Descriptions\",\n    \"0-1\": \"`xliff`\",\n    \"1-0\": \"User Generated Content\",\n    \"1-1\": \"`text` or `xliff`\",\n    \"2-0\": \"Subtitles\",\n    \"2-1\": \"`srt`\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Product Descriptions\"\n}\n[/block]\nOne of the best use cases for the Unbabel API is maintaining multilingual versions of product descriptions. In this way you'll automatically reach new markets in a seamless way.\n\nThis type of content is typically made of multiple parts like:\n* product title\n* product summary\n* product description\n\nTo maintain consistency in the translation, these parts should be grouped using the [XLIFF format](http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html). For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?xml version='1.0' encoding='utf-8'?>\\n<xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'>\\n  <file original='' source-language='en' datatype='TEXT'>\\n    <header/>\\n    <body>\\n      <trans-unit id='title'>\\n        <source>Product Title</source>\\n      </trans-unit>\\n      <trans-unit id='summary'>\\n        <source>The product summary</source>\\n      </trans-unit>\\n      <trans-unit id='description'>\\n        <source>The product description</source>\\n      </trans-unit>\\n    </body>\\n  </file>\\n</xliff>\",\n      \"language\": \"xml\",\n      \"name\": \"Product Description XLIFF\"\n    }\n  ]\n}\n[/block]\nThis XLIFF should then be used to set the text field of the translation request. Here's an example of how the complete request could look:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"text\\\" : \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='title'><source>Product Title</source></trans-unit><trans-unit id='description'><source>The product summary</source></trans-unit><trans-unit id='description'><source>The product description</source></trans-unit></body></file></xliff>\\\",\\n  \\\"target_language\\\" : \\\"pt\\\",\\n  \\\"text_format\\\" : \\\"xliff\\\"\\n  \\\"uid\\\" : \\\"1\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Product Description Translation Request\"\n    }\n  ]\n}\n[/block]\n**It's very important** that the field `text_format` is set to `xliff`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"User Generated Content\"\n}\n[/block]\nUser Generated Content is a perfect fit for Unbabel's scalable translation API, extending its global reach and bringing new audience. In this case, the `text_format` field should be set to `xliff` or `text`, depending if the content has multiple parts or just one. Here's an example request for the later\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"text\\\" : \\\"This text was written by a user\\\",\\n  \\\"target_language\\\" : \\\"pt\\\",\\n  \\\"text_format\\\" : \\\"text\\\"\\n  \\\"uid\\\" : \\\"1\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"User Generated Content Translation Request\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Subtitles\"\n}\n[/block]\nThe Unbabel API also supports the [SRT format](http://matroska.org/technical/specs/subtitles/srt.html) so that you can easily automate the translation of subtitles. In this case, the `text_format` field should be set to `srt`. Here's an example of a request to translate 2 subtitles\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"text\\\" : \\\"1\\\\n00:02:17,440 --> 00:02:20,375\\\\nWhat is the use of a book\\\\nwithout pictures or conversation?\\\\n\\\\n2\\\\n00:02:20,476 --> 00:02:22,501\\\\nOh dear! Oh dear! I shall be late!\\\",\\n  \\\"target_language\\\" : \\\"pt\\\",\\n  \\\"text_format\\\" : \\\"srt\\\"\\n  \\\"uid\\\" : \\\"1\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Subtitles Translation Request\"\n    }\n  ]\n}\n[/block]","updates":[],"category":"54afb7170cf42a0b001d5bf1","link_url":"","type":"basic","childrenPages":[]}

Use Cases


The following table summarises common use cases of the Unbabel API and the corresponding formats that should be set on the `text_format` field. [block:parameters] { "data": { "h-0": "Use Case", "h-1": "Format", "0-0": "Product Descriptions", "0-1": "`xliff`", "1-0": "User Generated Content", "1-1": "`text` or `xliff`", "2-0": "Subtitles", "2-1": "`srt`" }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Product Descriptions" } [/block] One of the best use cases for the Unbabel API is maintaining multilingual versions of product descriptions. In this way you'll automatically reach new markets in a seamless way. This type of content is typically made of multiple parts like: * product title * product summary * product description To maintain consistency in the translation, these parts should be grouped using the [XLIFF format](http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html). For example: [block:code] { "codes": [ { "code": "<?xml version='1.0' encoding='utf-8'?>\n<xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'>\n <file original='' source-language='en' datatype='TEXT'>\n <header/>\n <body>\n <trans-unit id='title'>\n <source>Product Title</source>\n </trans-unit>\n <trans-unit id='summary'>\n <source>The product summary</source>\n </trans-unit>\n <trans-unit id='description'>\n <source>The product description</source>\n </trans-unit>\n </body>\n </file>\n</xliff>", "language": "xml", "name": "Product Description XLIFF" } ] } [/block] This XLIFF should then be used to set the text field of the translation request. Here's an example of how the complete request could look: [block:code] { "codes": [ { "code": "{\n \"text\" : \"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='title'><source>Product Title</source></trans-unit><trans-unit id='description'><source>The product summary</source></trans-unit><trans-unit id='description'><source>The product description</source></trans-unit></body></file></xliff>\",\n \"target_language\" : \"pt\",\n \"text_format\" : \"xliff\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "Product Description Translation Request" } ] } [/block] **It's very important** that the field `text_format` is set to `xliff`. [block:api-header] { "type": "basic", "title": "User Generated Content" } [/block] User Generated Content is a perfect fit for Unbabel's scalable translation API, extending its global reach and bringing new audience. In this case, the `text_format` field should be set to `xliff` or `text`, depending if the content has multiple parts or just one. Here's an example request for the later [block:code] { "codes": [ { "code": "{\n \"text\" : \"This text was written by a user\",\n \"target_language\" : \"pt\",\n \"text_format\" : \"text\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "User Generated Content Translation Request" } ] } [/block] [block:api-header] { "type": "basic", "title": "Subtitles" } [/block] The Unbabel API also supports the [SRT format](http://matroska.org/technical/specs/subtitles/srt.html) so that you can easily automate the translation of subtitles. In this case, the `text_format` field should be set to `srt`. Here's an example of a request to translate 2 subtitles [block:code] { "codes": [ { "code": "{\n \"text\" : \"1\\n00:02:17,440 --> 00:02:20,375\\nWhat is the use of a book\\nwithout pictures or conversation?\\n\\n2\\n00:02:20,476 --> 00:02:22,501\\nOh dear! Oh dear! I shall be late!\",\n \"target_language\" : \"pt\",\n \"text_format\" : \"srt\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "Subtitles Translation Request" } ] } [/block]
The following table summarises common use cases of the Unbabel API and the corresponding formats that should be set on the `text_format` field. [block:parameters] { "data": { "h-0": "Use Case", "h-1": "Format", "0-0": "Product Descriptions", "0-1": "`xliff`", "1-0": "User Generated Content", "1-1": "`text` or `xliff`", "2-0": "Subtitles", "2-1": "`srt`" }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Product Descriptions" } [/block] One of the best use cases for the Unbabel API is maintaining multilingual versions of product descriptions. In this way you'll automatically reach new markets in a seamless way. This type of content is typically made of multiple parts like: * product title * product summary * product description To maintain consistency in the translation, these parts should be grouped using the [XLIFF format](http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html). For example: [block:code] { "codes": [ { "code": "<?xml version='1.0' encoding='utf-8'?>\n<xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'>\n <file original='' source-language='en' datatype='TEXT'>\n <header/>\n <body>\n <trans-unit id='title'>\n <source>Product Title</source>\n </trans-unit>\n <trans-unit id='summary'>\n <source>The product summary</source>\n </trans-unit>\n <trans-unit id='description'>\n <source>The product description</source>\n </trans-unit>\n </body>\n </file>\n</xliff>", "language": "xml", "name": "Product Description XLIFF" } ] } [/block] This XLIFF should then be used to set the text field of the translation request. Here's an example of how the complete request could look: [block:code] { "codes": [ { "code": "{\n \"text\" : \"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='title'><source>Product Title</source></trans-unit><trans-unit id='description'><source>The product summary</source></trans-unit><trans-unit id='description'><source>The product description</source></trans-unit></body></file></xliff>\",\n \"target_language\" : \"pt\",\n \"text_format\" : \"xliff\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "Product Description Translation Request" } ] } [/block] **It's very important** that the field `text_format` is set to `xliff`. [block:api-header] { "type": "basic", "title": "User Generated Content" } [/block] User Generated Content is a perfect fit for Unbabel's scalable translation API, extending its global reach and bringing new audience. In this case, the `text_format` field should be set to `xliff` or `text`, depending if the content has multiple parts or just one. Here's an example request for the later [block:code] { "codes": [ { "code": "{\n \"text\" : \"This text was written by a user\",\n \"target_language\" : \"pt\",\n \"text_format\" : \"text\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "User Generated Content Translation Request" } ] } [/block] [block:api-header] { "type": "basic", "title": "Subtitles" } [/block] The Unbabel API also supports the [SRT format](http://matroska.org/technical/specs/subtitles/srt.html) so that you can easily automate the translation of subtitles. In this case, the `text_format` field should be set to `srt`. Here's an example of a request to translate 2 subtitles [block:code] { "codes": [ { "code": "{\n \"text\" : \"1\\n00:02:17,440 --> 00:02:20,375\\nWhat is the use of a book\\nwithout pictures or conversation?\\n\\n2\\n00:02:20,476 --> 00:02:22,501\\nOh dear! Oh dear! I shall be late!\",\n \"target_language\" : \"pt\",\n \"text_format\" : \"srt\"\n \"uid\" : \"1\"\n}", "language": "json", "name": "Subtitles Translation Request" } ] } [/block]
{"_id":"566edcaa7ffa002300c3cafe","isReference":false,"slug":"tutorial","link_external":false,"order":2,"user":"5669472c08f90021008e887d","__v":33,"createdAt":"2015-12-14T15:13:46.625Z","excerpt":"","githubsync":"","hidden":false,"category":"54afb7170cf42a0b001d5bf1","parentDoc":null,"project":"54ad6c769219922100751763","title":"Tutorials","version":"54afb7160cf42a0b001d5bf0","type":"basic","updates":[],"api":{"params":[],"results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","url":"","auth":"required"},"body":"You can try out the Unbabel API for free using its sandbox. In sandbox mode, each request is processed automatically using machine translation with no involvement of Unbabel Editors (otherwise, we would have to pay for their work time). To simulate production behavior, we hold the translation for 2 minutes and then post it to the defined callback endpoint.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Setting Up a Sandbox Account\"\n}\n[/block]\nThe first step to setup your sandbox is to request a Sandbox API Key by sending an email to **api@unbabel.com**. You can simply send us an email like this one:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"To: api@unbabel.com\\nSubject: Sandbox access\\n\\nPlease give me access to the API Sandbox.\",\n      \"language\": \"text\",\n      \"name\": \"Sandbox Request Email\"\n    }\n  ]\n}\n[/block]\nIn reply, you'll receive an email like the following one, with your **Sandbox Username** and **API Key**:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"From: api@unbabel.com\\nSubject: Unbabel API Sandbox\\n\\nPlease use the following credentials to use the API Sandbox:\\n\\nUsername: <username>\\nEmail: <email>\\nAPI Key: <api_key>\\n\\nThe documentation for the API can be found at http://developers.unbabel.com/\",\n      \"language\": \"text\",\n      \"name\": \"Sandbox Request Response Email\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Translating \\\"Hello, World!\\\"\"\n}\n[/block]\nOnce you have setup your sandbox, requesting a translation is very simple. You just need to do a HTTP request to the `translation` endpoint. Using a tool like cURL (learn more at [http://curl.haxx.se](http://curl.haxx.se)) is super easy. If this tool is not familiar to you, you can read a short intro about it with examples at [http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl](http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl). An alternative to cURL is [POSTMAN](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en), an easy-to-use Chrome extension for making HTTP requests. You can also use one of our SDKs described in the SDKs sections.\n\nUsing cURL, translating \"Hello, world!\" would be done by executing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d '{\\\"text\\\" : \\\"Hello, world!\\\", \\\"target_language\\\" : \\\"pt\\\", \\\"text_format\\\" : \\\"text\\\"}'\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\nIn response you would have:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"balance\\\": 99943.0,\\n  \\\"client\\\": \\\"username\\\",\\n  \\\"price\\\": 6.0,\\n  \\\"source_language\\\": \\\"en\\\",\\n  \\\"status\\\": \\\"new\\\",\\n  \\\"target_language\\\": \\\"pt\\\",\\n  \\\"text\\\": \\\"Hello, world!\\\",\\n  \\\"text_format\\\": \\\"text\\\",\\n  \\\"uid\\\": \\\"ac1a53a264\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nTo check the translation status you would use the returned job `uid` and do:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/ac1a53a264/\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\nPlease note that the \"/\" after the job uid is mandatory. Depending on the elapsed time between the two requests, you could get something like:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"balance\\\": 99937.0,\\n  \\\"client\\\": \\\"username\\\",\\n  \\\"price\\\": 6.0,\\n  \\\"source_language\\\": \\\"en\\\",\\n  \\\"status\\\": \\\"translating\\\",\\n  \\\"target_language\\\": \\\"pt\\\",\\n  \\\"text\\\": \\\"Hello, world!\\\",\\n  \\\"text_format\\\": \\\"text\\\",\\n  \\\"uid\\\": \\\"ac1a53a264\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response: translation in progress\"\n    }\n  ]\n}\n[/block]\nOr, immediately, the translation itself:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"balance\\\": 99937.0,\\n\\t\\\"client\\\": \\\"username\\\",\\n\\t\\\"price\\\": 6.0,\\n\\t\\\"source_language\\\": \\\"en\\\",\\n\\t\\\"status\\\": \\\"completed\\\",\\n\\t\\\"target_language\\\": \\\"pt\\\",\\n\\t\\\"text\\\": \\\"Hello, world!\\\",\\n\\t\\\"text_format\\\": \\\"text\\\",\\n\\t\\\"translatedText\\\": \\\"Olá Mundo!\\\",\\n\\t\\\"uid\\\": \\\"ac1a53a264\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response: translation completed\"\n    }\n  ]\n}\n[/block]\nThese two possible responses depend on the time the translation takes to be completed. Since this relies on human processing, it may range from a few minutes to hours.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Translating a Product Description\"\n}\n[/block]\nA product description is typically made of multiple parts like: product name, summary and description.  As described in [Use Cases](doc:2-use-cases), you should always use the XLIFF format for this kind of content, sending all content parts in a single translation request. Splitting content parts in different translation requests could lead to inconsistencies in the translation.\n\nLet's use as an example the following product:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Product Name\",\n    \"h-1\": \"Product Description\",\n    \"0-0\": \"Alice In Wonderland teapot\",\n    \"0-1\": \"Beautiful porcelain tea pot with Alice and the Cheshire cat\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\nIn XLIFF format this product could be represented like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?xml version='1.0' encoding='utf-8'?>\\n<xliff xmlns=\\\"urn:oasis:names:tc:xliff:document:1.2\\\" version=\\\"1.2\\\">\\n  <file original=\\\"\\\" source-language=\\\"en\\\" datatype=\\\"TEXT\\\">\\n    <header/>\\n    <body>\\n      <trans-unit id=\\\"name\\\" >\\n        <source>Alice In Wonderland teapot</source>\\n      </trans-unit>\\n      <trans-unit id=\\\"description\\\">\\n        <source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source>\\n      </trans-unit>\\n    </body>\\n  </file>\\n</xliff>\",\n      \"language\": \"xml\",\n      \"name\": \"Product Description XLIFF\"\n    }\n  ]\n}\n[/block]\nUsing cURL, you can translate this product description by doing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \\\"{\\\\\\\"text\\\\\\\" : \\\\\\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\\\\\", \\\\\\\"target_language\\\\\\\" : \\\\\\\"pt\\\\\\\", \\\\\\\"text_format\\\\\\\" : \\\\\\\"xliff\\\\\\\"}\\\"\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"balance\\\": 99922.0,\\n  \\\"client\\\": \\\"username\\\",\\n  \\\"price\\\": 42.0,\\n  \\\"source_language\\\": \\\"en\\\",\\n  \\\"status\\\": \\\"new\\\",\\n  \\\"target_language\\\": \\\"pt\\\",\\n  \\\"text_format\\\": \\\"xliff\\\",\\n  \\\"uid\\\": \\\"937faff2b5\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nTo check the translation status, you would do:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/937faff2b5/\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\nIn case the translation process has finished, the response would be:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"balance\\\": 99880.0,\\n  \\\"client\\\": \\\"username\\\",\\n  \\\"price\\\": 42.0,\\n  \\\"source_language\\\": \\\"en\\\",\\n  \\\"status\\\": \\\"completed\\\",\\n  \\\"target_language\\\": \\\"pt\\\",\\n  \\\"text\\\": \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\",\\n  \\\"text_format\\\": \\\"xliff\\\",\\n  \\\"translatedText\\\": \\\"<?xml version=\\\\\\\"1.0\\\\\\\" encoding=\\\\\\\"utf-8\\\\\\\"?><xliff xmlns=\\\\\\\"urn:oasis:names:tc:xliff:document:1.2\\\\\\\" version=\\\\\\\"1.2\\\\\\\"><file original=\\\\\\\"\\\\\\\" source-language=\\\\\\\"en\\\\\\\" datatype=\\\\\\\"TEXT\\\\\\\"><header/><body><trans-unit id=\\\\\\\"name\\\\\\\"><source>Alice In Wonderland teapot</source><target>Alice In Wonderland bule</target></trans-unit><trans-unit id=\\\\\\\"description\\\\\\\"><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source><target>Bule de chá de porcelana bonita com Alice e o gato de Cheshire</target></trans-unit></body></file></xliff>\\\",\\n        \\\"uid\\\": \\\"937faff2b5\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Setting Translation Instructions, Tone and Topics\"\n}\n[/block]\nAs mentioned in [Getting Started](doc:getting-integrated), it's very important that you give as much context as possible about your content. Only in this way,  Unbabel Editors will understand translation preferences like the tone that should be used (eg: informal or formal) and the type of content — translating a product description is quite different from translating user generated content. The fields `instructions`, `tone` and `topics` are used to associate this information with the translation request.\n\nLet's use as an example the translation of product descriptions for an e-commerce website (of crafts and technology). Using cURL, you could translate a product description giving context about it by doing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \\\"{\\\\\\\"text\\\\\\\" : \\\\\\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\\\\\", \\\\\\\"target_language\\\\\\\" : \\\\\\\"pt\\\\\\\", \\\\\\\"text_format\\\\\\\" : \\\\\\\"xliff\\\\\\\", \\\\\\\"instructions\\\\\\\" : \\\\\\\"This is a product description for an e-commerce website. Check www.ecommerce.com for reference\\\\\\\", \\\\\\\"tone\\\\\\\" : \\\\\\\"Formal\\\\\\\", \\\\\\\"topics\\\\\\\" : [\\\\\\\"tech\\\\\\\", \\\\\\\"crafts\\\\\\\"]}\\\"\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"balance\\\": 99880.0,\\n  \\\"client\\\": \\\"pdimas\\\",\\n  \\\"instructions\\\": \\\"This is a product description for an e-commerce website. Check www.ecommerce.com for reference\\\",\\n  \\\"price\\\": 42.0,\\n  \\\"source_language\\\": \\\"en\\\",\\n  \\\"status\\\": \\\"new\\\",\\n  \\\"target_language\\\": \\\"pt\\\",\\n  \\\"tone\\\": \\\"Formal\\\",\\n  \\\"topics\\\": [\\\"tech\\\", \\\"crafts\\\"],\\n  \\\"uid\\\": \\\"8926cbec74\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nYou can check the list of possible tones using cURL by doing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X GET https://sandbox.unbabel.com/tapi/v2/tone/\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"objects\\\": [{\\n\\t\\t\\\"tone\\\": {\\n\\t\\t\\t\\\"description\\\": \\\"Informal style\\\",\\n\\t\\t\\t\\\"name\\\": \\\"Informal\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"tone\\\": {\\n\\t\\t\\t\\\"description\\\": \\\"Formal style\\\",\\n\\t\\t\\t\\\"name\\\": \\\"Formal\\\"\\n\\t\\t}\\n\\t}]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nAnd, to check the list of possible topics, you can do:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: ApiKey username:apikey\\\" -H \\\"Content-Type: application/json\\\" -X GET https://sandbox.unbabel.com/tapi/v2/topic/\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"objects\\\": [{\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"politics\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"gossip\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"sex & relationships\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"crafts\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"parenting\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"startups\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"tech\\\"\\n\\t\\t}\\n\\t}, {\\n\\t\\t\\\"topic\\\": {\\n\\t\\t\\t\\\"name\\\": \\\"sports\\\"\\n\\t\\t}\\n\\t}]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nOn the `instructions` field you should send any text that may help in the translation process.","link_url":"","sync_unique":"","next":{"description":"","pages":[]},"childrenPages":[]}

Tutorials


You can try out the Unbabel API for free using its sandbox. In sandbox mode, each request is processed automatically using machine translation with no involvement of Unbabel Editors (otherwise, we would have to pay for their work time). To simulate production behavior, we hold the translation for 2 minutes and then post it to the defined callback endpoint. [block:api-header] { "type": "basic", "title": "Setting Up a Sandbox Account" } [/block] The first step to setup your sandbox is to request a Sandbox API Key by sending an email to **api@unbabel.com**. You can simply send us an email like this one: [block:code] { "codes": [ { "code": "To: api@unbabel.com\nSubject: Sandbox access\n\nPlease give me access to the API Sandbox.", "language": "text", "name": "Sandbox Request Email" } ] } [/block] In reply, you'll receive an email like the following one, with your **Sandbox Username** and **API Key**: [block:code] { "codes": [ { "code": "From: api@unbabel.com\nSubject: Unbabel API Sandbox\n\nPlease use the following credentials to use the API Sandbox:\n\nUsername: <username>\nEmail: <email>\nAPI Key: <api_key>\n\nThe documentation for the API can be found at http://developers.unbabel.com/", "language": "text", "name": "Sandbox Request Response Email" } ] } [/block] [block:api-header] { "type": "basic", "title": "Translating \"Hello, World!\"" } [/block] Once you have setup your sandbox, requesting a translation is very simple. You just need to do a HTTP request to the `translation` endpoint. Using a tool like cURL (learn more at [http://curl.haxx.se](http://curl.haxx.se)) is super easy. If this tool is not familiar to you, you can read a short intro about it with examples at [http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl](http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl). An alternative to cURL is [POSTMAN](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en), an easy-to-use Chrome extension for making HTTP requests. You can also use one of our SDKs described in the SDKs sections. Using cURL, translating "Hello, world!" would be done by executing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d '{\"text\" : \"Hello, world!\", \"target_language\" : \"pt\", \"text_format\" : \"text\"}'", "language": "shell", "name": "Request" } ] } [/block] In response you would have: [block:code] { "codes": [ { "code": "{\n \"balance\": 99943.0,\n \"client\": \"username\",\n \"price\": 6.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"text\": \"Hello, world!\",\n \"text_format\": \"text\",\n \"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response" } ] } [/block] To check the translation status you would use the returned job `uid` and do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/ac1a53a264/", "language": "shell", "name": "Request" } ] } [/block] Please note that the "/" after the job uid is mandatory. Depending on the elapsed time between the two requests, you could get something like: [block:code] { "codes": [ { "code": "{\n \"balance\": 99937.0,\n \"client\": \"username\",\n \"price\": 6.0,\n \"source_language\": \"en\",\n \"status\": \"translating\",\n \"target_language\": \"pt\",\n \"text\": \"Hello, world!\",\n \"text_format\": \"text\",\n \"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response: translation in progress" } ] } [/block] Or, immediately, the translation itself: [block:code] { "codes": [ { "code": "{\n\t\"balance\": 99937.0,\n\t\"client\": \"username\",\n\t\"price\": 6.0,\n\t\"source_language\": \"en\",\n\t\"status\": \"completed\",\n\t\"target_language\": \"pt\",\n\t\"text\": \"Hello, world!\",\n\t\"text_format\": \"text\",\n\t\"translatedText\": \"Olá Mundo!\",\n\t\"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response: translation completed" } ] } [/block] These two possible responses depend on the time the translation takes to be completed. Since this relies on human processing, it may range from a few minutes to hours. [block:api-header] { "type": "basic", "title": "Translating a Product Description" } [/block] A product description is typically made of multiple parts like: product name, summary and description. As described in [Use Cases](doc:2-use-cases), you should always use the XLIFF format for this kind of content, sending all content parts in a single translation request. Splitting content parts in different translation requests could lead to inconsistencies in the translation. Let's use as an example the following product: [block:parameters] { "data": { "h-0": "Product Name", "h-1": "Product Description", "0-0": "Alice In Wonderland teapot", "0-1": "Beautiful porcelain tea pot with Alice and the Cheshire cat" }, "cols": 2, "rows": 1 } [/block] In XLIFF format this product could be represented like this: [block:code] { "codes": [ { "code": "<?xml version='1.0' encoding='utf-8'?>\n<xliff xmlns=\"urn:oasis:names:tc:xliff:document:1.2\" version=\"1.2\">\n <file original=\"\" source-language=\"en\" datatype=\"TEXT\">\n <header/>\n <body>\n <trans-unit id=\"name\" >\n <source>Alice In Wonderland teapot</source>\n </trans-unit>\n <trans-unit id=\"description\">\n <source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source>\n </trans-unit>\n </body>\n </file>\n</xliff>", "language": "xml", "name": "Product Description XLIFF" } ] } [/block] Using cURL, you can translate this product description by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \"{\\\"text\\\" : \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\", \\\"target_language\\\" : \\\"pt\\\", \\\"text_format\\\" : \\\"xliff\\\"}\"", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"balance\": 99922.0,\n \"client\": \"username\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"text_format\": \"xliff\",\n \"uid\": \"937faff2b5\"\n}", "language": "json", "name": "Response" } ] } [/block] To check the translation status, you would do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/937faff2b5/", "language": "shell", "name": "Request" } ] } [/block] In case the translation process has finished, the response would be: [block:code] { "codes": [ { "code": "{\n \"balance\": 99880.0,\n \"client\": \"username\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"completed\",\n \"target_language\": \"pt\",\n \"text\": \"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\",\n \"text_format\": \"xliff\",\n \"translatedText\": \"<?xml version=\\\"1.0\\\" encoding=\\\"utf-8\\\"?><xliff xmlns=\\\"urn:oasis:names:tc:xliff:document:1.2\\\" version=\\\"1.2\\\"><file original=\\\"\\\" source-language=\\\"en\\\" datatype=\\\"TEXT\\\"><header/><body><trans-unit id=\\\"name\\\"><source>Alice In Wonderland teapot</source><target>Alice In Wonderland bule</target></trans-unit><trans-unit id=\\\"description\\\"><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source><target>Bule de chá de porcelana bonita com Alice e o gato de Cheshire</target></trans-unit></body></file></xliff>\",\n \"uid\": \"937faff2b5\"\n}", "language": "json", "name": "Response" } ] } [/block] [block:api-header] { "type": "basic", "title": "Setting Translation Instructions, Tone and Topics" } [/block] As mentioned in [Getting Started](doc:getting-integrated), it's very important that you give as much context as possible about your content. Only in this way, Unbabel Editors will understand translation preferences like the tone that should be used (eg: informal or formal) and the type of content — translating a product description is quite different from translating user generated content. The fields `instructions`, `tone` and `topics` are used to associate this information with the translation request. Let's use as an example the translation of product descriptions for an e-commerce website (of crafts and technology). Using cURL, you could translate a product description giving context about it by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \"{\\\"text\\\" : \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\", \\\"target_language\\\" : \\\"pt\\\", \\\"text_format\\\" : \\\"xliff\\\", \\\"instructions\\\" : \\\"This is a product description for an e-commerce website. Check www.ecommerce.com for reference\\\", \\\"tone\\\" : \\\"Formal\\\", \\\"topics\\\" : [\\\"tech\\\", \\\"crafts\\\"]}\"", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"balance\": 99880.0,\n \"client\": \"pdimas\",\n \"instructions\": \"This is a product description for an e-commerce website. Check www.ecommerce.com for reference\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"tone\": \"Formal\",\n \"topics\": [\"tech\", \"crafts\"],\n \"uid\": \"8926cbec74\"\n}", "language": "json", "name": "Response" } ] } [/block] You can check the list of possible tones using cURL by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/tone/", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n\t\"objects\": [{\n\t\t\"tone\": {\n\t\t\t\"description\": \"Informal style\",\n\t\t\t\"name\": \"Informal\"\n\t\t}\n\t}, {\n\t\t\"tone\": {\n\t\t\t\"description\": \"Formal style\",\n\t\t\t\"name\": \"Formal\"\n\t\t}\n\t}]\n}", "language": "json", "name": "Response" } ] } [/block] And, to check the list of possible topics, you can do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/topic/", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n\t\"objects\": [{\n\t\t\"topic\": {\n\t\t\t\"name\": \"politics\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"gossip\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"sex & relationships\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"crafts\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"parenting\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"startups\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"tech\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"sports\"\n\t\t}\n\t}]\n}", "language": "json", "name": "Response" } ] } [/block] On the `instructions` field you should send any text that may help in the translation process.
You can try out the Unbabel API for free using its sandbox. In sandbox mode, each request is processed automatically using machine translation with no involvement of Unbabel Editors (otherwise, we would have to pay for their work time). To simulate production behavior, we hold the translation for 2 minutes and then post it to the defined callback endpoint. [block:api-header] { "type": "basic", "title": "Setting Up a Sandbox Account" } [/block] The first step to setup your sandbox is to request a Sandbox API Key by sending an email to **api@unbabel.com**. You can simply send us an email like this one: [block:code] { "codes": [ { "code": "To: api@unbabel.com\nSubject: Sandbox access\n\nPlease give me access to the API Sandbox.", "language": "text", "name": "Sandbox Request Email" } ] } [/block] In reply, you'll receive an email like the following one, with your **Sandbox Username** and **API Key**: [block:code] { "codes": [ { "code": "From: api@unbabel.com\nSubject: Unbabel API Sandbox\n\nPlease use the following credentials to use the API Sandbox:\n\nUsername: <username>\nEmail: <email>\nAPI Key: <api_key>\n\nThe documentation for the API can be found at http://developers.unbabel.com/", "language": "text", "name": "Sandbox Request Response Email" } ] } [/block] [block:api-header] { "type": "basic", "title": "Translating \"Hello, World!\"" } [/block] Once you have setup your sandbox, requesting a translation is very simple. You just need to do a HTTP request to the `translation` endpoint. Using a tool like cURL (learn more at [http://curl.haxx.se](http://curl.haxx.se)) is super easy. If this tool is not familiar to you, you can read a short intro about it with examples at [http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl](http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl). An alternative to cURL is [POSTMAN](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en), an easy-to-use Chrome extension for making HTTP requests. You can also use one of our SDKs described in the SDKs sections. Using cURL, translating "Hello, world!" would be done by executing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d '{\"text\" : \"Hello, world!\", \"target_language\" : \"pt\", \"text_format\" : \"text\"}'", "language": "shell", "name": "Request" } ] } [/block] In response you would have: [block:code] { "codes": [ { "code": "{\n \"balance\": 99943.0,\n \"client\": \"username\",\n \"price\": 6.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"text\": \"Hello, world!\",\n \"text_format\": \"text\",\n \"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response" } ] } [/block] To check the translation status you would use the returned job `uid` and do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/ac1a53a264/", "language": "shell", "name": "Request" } ] } [/block] Please note that the "/" after the job uid is mandatory. Depending on the elapsed time between the two requests, you could get something like: [block:code] { "codes": [ { "code": "{\n \"balance\": 99937.0,\n \"client\": \"username\",\n \"price\": 6.0,\n \"source_language\": \"en\",\n \"status\": \"translating\",\n \"target_language\": \"pt\",\n \"text\": \"Hello, world!\",\n \"text_format\": \"text\",\n \"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response: translation in progress" } ] } [/block] Or, immediately, the translation itself: [block:code] { "codes": [ { "code": "{\n\t\"balance\": 99937.0,\n\t\"client\": \"username\",\n\t\"price\": 6.0,\n\t\"source_language\": \"en\",\n\t\"status\": \"completed\",\n\t\"target_language\": \"pt\",\n\t\"text\": \"Hello, world!\",\n\t\"text_format\": \"text\",\n\t\"translatedText\": \"Olá Mundo!\",\n\t\"uid\": \"ac1a53a264\"\n}", "language": "json", "name": "Response: translation completed" } ] } [/block] These two possible responses depend on the time the translation takes to be completed. Since this relies on human processing, it may range from a few minutes to hours. [block:api-header] { "type": "basic", "title": "Translating a Product Description" } [/block] A product description is typically made of multiple parts like: product name, summary and description. As described in [Use Cases](doc:2-use-cases), you should always use the XLIFF format for this kind of content, sending all content parts in a single translation request. Splitting content parts in different translation requests could lead to inconsistencies in the translation. Let's use as an example the following product: [block:parameters] { "data": { "h-0": "Product Name", "h-1": "Product Description", "0-0": "Alice In Wonderland teapot", "0-1": "Beautiful porcelain tea pot with Alice and the Cheshire cat" }, "cols": 2, "rows": 1 } [/block] In XLIFF format this product could be represented like this: [block:code] { "codes": [ { "code": "<?xml version='1.0' encoding='utf-8'?>\n<xliff xmlns=\"urn:oasis:names:tc:xliff:document:1.2\" version=\"1.2\">\n <file original=\"\" source-language=\"en\" datatype=\"TEXT\">\n <header/>\n <body>\n <trans-unit id=\"name\" >\n <source>Alice In Wonderland teapot</source>\n </trans-unit>\n <trans-unit id=\"description\">\n <source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source>\n </trans-unit>\n </body>\n </file>\n</xliff>", "language": "xml", "name": "Product Description XLIFF" } ] } [/block] Using cURL, you can translate this product description by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \"{\\\"text\\\" : \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\", \\\"target_language\\\" : \\\"pt\\\", \\\"text_format\\\" : \\\"xliff\\\"}\"", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"balance\": 99922.0,\n \"client\": \"username\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"text_format\": \"xliff\",\n \"uid\": \"937faff2b5\"\n}", "language": "json", "name": "Response" } ] } [/block] To check the translation status, you would do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/translation/937faff2b5/", "language": "shell", "name": "Request" } ] } [/block] In case the translation process has finished, the response would be: [block:code] { "codes": [ { "code": "{\n \"balance\": 99880.0,\n \"client\": \"username\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"completed\",\n \"target_language\": \"pt\",\n \"text\": \"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\",\n \"text_format\": \"xliff\",\n \"translatedText\": \"<?xml version=\\\"1.0\\\" encoding=\\\"utf-8\\\"?><xliff xmlns=\\\"urn:oasis:names:tc:xliff:document:1.2\\\" version=\\\"1.2\\\"><file original=\\\"\\\" source-language=\\\"en\\\" datatype=\\\"TEXT\\\"><header/><body><trans-unit id=\\\"name\\\"><source>Alice In Wonderland teapot</source><target>Alice In Wonderland bule</target></trans-unit><trans-unit id=\\\"description\\\"><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source><target>Bule de chá de porcelana bonita com Alice e o gato de Cheshire</target></trans-unit></body></file></xliff>\",\n \"uid\": \"937faff2b5\"\n}", "language": "json", "name": "Response" } ] } [/block] [block:api-header] { "type": "basic", "title": "Setting Translation Instructions, Tone and Topics" } [/block] As mentioned in [Getting Started](doc:getting-integrated), it's very important that you give as much context as possible about your content. Only in this way, Unbabel Editors will understand translation preferences like the tone that should be used (eg: informal or formal) and the type of content — translating a product description is quite different from translating user generated content. The fields `instructions`, `tone` and `topics` are used to associate this information with the translation request. Let's use as an example the translation of product descriptions for an e-commerce website (of crafts and technology). Using cURL, you could translate a product description giving context about it by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X POST https://sandbox.unbabel.com/tapi/v2/translation/ -d \"{\\\"text\\\" : \\\"<?xml version='1.0' encoding='utf-8'?><xliff xmlns='urn:oasis:names:tc:xliff:document:1.2' version='1.2'><file original='' source-language='en' datatype='TEXT'><header/><body><trans-unit id='name'><source>Alice In Wonderland teapot</source></trans-unit><trans-unit id='description'><source>Beautiful porcelain tea pot with Alice and the Cheshire cat</source></trans-unit></body></file></xliff>\\\", \\\"target_language\\\" : \\\"pt\\\", \\\"text_format\\\" : \\\"xliff\\\", \\\"instructions\\\" : \\\"This is a product description for an e-commerce website. Check www.ecommerce.com for reference\\\", \\\"tone\\\" : \\\"Formal\\\", \\\"topics\\\" : [\\\"tech\\\", \\\"crafts\\\"]}\"", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"balance\": 99880.0,\n \"client\": \"pdimas\",\n \"instructions\": \"This is a product description for an e-commerce website. Check www.ecommerce.com for reference\",\n \"price\": 42.0,\n \"source_language\": \"en\",\n \"status\": \"new\",\n \"target_language\": \"pt\",\n \"tone\": \"Formal\",\n \"topics\": [\"tech\", \"crafts\"],\n \"uid\": \"8926cbec74\"\n}", "language": "json", "name": "Response" } ] } [/block] You can check the list of possible tones using cURL by doing: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/tone/", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n\t\"objects\": [{\n\t\t\"tone\": {\n\t\t\t\"description\": \"Informal style\",\n\t\t\t\"name\": \"Informal\"\n\t\t}\n\t}, {\n\t\t\"tone\": {\n\t\t\t\"description\": \"Formal style\",\n\t\t\t\"name\": \"Formal\"\n\t\t}\n\t}]\n}", "language": "json", "name": "Response" } ] } [/block] And, to check the list of possible topics, you can do: [block:code] { "codes": [ { "code": "curl -H \"Authorization: ApiKey username:apikey\" -H \"Content-Type: application/json\" -X GET https://sandbox.unbabel.com/tapi/v2/topic/", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n\t\"objects\": [{\n\t\t\"topic\": {\n\t\t\t\"name\": \"politics\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"gossip\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"sex & relationships\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"crafts\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"parenting\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"startups\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"tech\"\n\t\t}\n\t}, {\n\t\t\"topic\": {\n\t\t\t\"name\": \"sports\"\n\t\t}\n\t}]\n}", "language": "json", "name": "Response" } ] } [/block] On the `instructions` field you should send any text that may help in the translation process.
{"_id":"566eeb0e7ffa002300c3cb26","type":"basic","excerpt":"","hidden":false,"link_external":false,"link_url":"","body":"To easily check the status of translation requests, you can access [http://sandbox.unbabel.com](http://sandbox.unbabel.com). After signing-in using your email and Sandbox API Key, you'll see the list of sent translation requests:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2MBWOrtYQe6B8C7V4jJB_unbabel_api_sandbox_screenshot_20151214.png\",\n        \"unbabel_api_sandbox_screenshot_20151214.png\",\n        \"1018\",\n        \"119\",\n        \"#638391\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]","parentDoc":null,"updates":[],"order":3,"project":"54ad6c769219922100751763","slug":"sandbox-status-page","title":"Sandbox Status Page","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"category":"54afb7170cf42a0b001d5bf1","createdAt":"2015-12-14T16:15:10.224Z","githubsync":"","user":"5669472c08f90021008e887d","__v":1,"sync_unique":"","version":"54afb7160cf42a0b001d5bf0","childrenPages":[]}

Sandbox Status Page


To easily check the status of translation requests, you can access [http://sandbox.unbabel.com](http://sandbox.unbabel.com). After signing-in using your email and Sandbox API Key, you'll see the list of sent translation requests: [block:image] { "images": [ { "image": [ "https://files.readme.io/2MBWOrtYQe6B8C7V4jJB_unbabel_api_sandbox_screenshot_20151214.png", "unbabel_api_sandbox_screenshot_20151214.png", "1018", "119", "#638391", "" ] } ] } [/block]
To easily check the status of translation requests, you can access [http://sandbox.unbabel.com](http://sandbox.unbabel.com). After signing-in using your email and Sandbox API Key, you'll see the list of sent translation requests: [block:image] { "images": [ { "image": [ "https://files.readme.io/2MBWOrtYQe6B8C7V4jJB_unbabel_api_sandbox_screenshot_20151214.png", "unbabel_api_sandbox_screenshot_20151214.png", "1018", "119", "#638391", "" ] } ] } [/block]
{"_id":"566eeb81c1b00f1900ffd3c1","category":"54afb7170cf42a0b001d5bf1","excerpt":"","isReference":false,"sync_unique":"","title":"Getting a Production API Key","updates":[],"user":"5669472c08f90021008e887d","__v":2,"version":"54afb7160cf42a0b001d5bf0","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"parentDoc":null,"type":"basic","body":"After having your code tested on the free API Sandbox, you may proceed to the production environment to benefit from Unbabel's scalable human quality translation.\n\nIf you have not yet created an account at Unbabel you'll now need to do it at: [https://unbabel.com/customer/signup](https://unbabel.com/customer/signup).\n\nOn your Dashboard, you can find the Production API Key on the API Access tab. You can also view it directly opening [https://unbabel.com/customer/dashboard/api_access/](https://unbabel.com/customer/dashboard/api_access/).\n\nPlease note that instead of **https://sandbox.unbabel.com** you should now use the production endpoint **https://api.unbabel.com**.","project":"54ad6c769219922100751763","createdAt":"2015-12-14T16:17:05.765Z","next":{"description":"","pages":[]},"slug":"getting-a-production-api-key","api":{"settings":"","url":"","auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]}},"childrenPages":[]}

Getting a Production API Key


After having your code tested on the free API Sandbox, you may proceed to the production environment to benefit from Unbabel's scalable human quality translation. If you have not yet created an account at Unbabel you'll now need to do it at: [https://unbabel.com/customer/signup](https://unbabel.com/customer/signup). On your Dashboard, you can find the Production API Key on the API Access tab. You can also view it directly opening [https://unbabel.com/customer/dashboard/api_access/](https://unbabel.com/customer/dashboard/api_access/). Please note that instead of **https://sandbox.unbabel.com** you should now use the production endpoint **https://api.unbabel.com**.
After having your code tested on the free API Sandbox, you may proceed to the production environment to benefit from Unbabel's scalable human quality translation. If you have not yet created an account at Unbabel you'll now need to do it at: [https://unbabel.com/customer/signup](https://unbabel.com/customer/signup). On your Dashboard, you can find the Production API Key on the API Access tab. You can also view it directly opening [https://unbabel.com/customer/dashboard/api_access/](https://unbabel.com/customer/dashboard/api_access/). Please note that instead of **https://sandbox.unbabel.com** you should now use the production endpoint **https://api.unbabel.com**.
{"_id":"566eebb746acce17000c88b6","next":{"description":"","pages":[]},"order":5,"updates":[],"excerpt":"","hidden":false,"isReference":false,"link_url":"","parentDoc":null,"slug":"api-usage-notes","__v":1,"category":"54afb7170cf42a0b001d5bf1","createdAt":"2015-12-14T16:17:59.404Z","link_external":false,"title":"API Usage Notes","user":"5669472c08f90021008e887d","version":"54afb7160cf42a0b001d5bf0","api":{"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","auth":"required","params":[]},"body":"When using the Unbabel API:\n\n* all paths are prefixed with https://api.unbabel.com or https://sandbox.unbabel.com\n\n* all data sent to non-GET endpoints is in the JSON format\n\n* all responses are in the JSON format\n\n* for all endpoints, you MUST use the trailing /\n\n* all prices and balances are in USD cents","githubsync":"","project":"54ad6c769219922100751763","sync_unique":"","type":"basic","childrenPages":[]}

API Usage Notes


When using the Unbabel API: * all paths are prefixed with https://api.unbabel.com or https://sandbox.unbabel.com * all data sent to non-GET endpoints is in the JSON format * all responses are in the JSON format * for all endpoints, you MUST use the trailing / * all prices and balances are in USD cents
When using the Unbabel API: * all paths are prefixed with https://api.unbabel.com or https://sandbox.unbabel.com * all data sent to non-GET endpoints is in the JSON format * all responses are in the JSON format * for all endpoints, you MUST use the trailing / * all prices and balances are in USD cents
{"_id":"54afcb5aed9ada1400afbf5d","version":"54afb7160cf42a0b001d5bf0","body":"We currently have several SDKs in various stages of development. If your preferred language's SDK needs development or does not exist, please get in touch with us at api@unbabel.com! We are always looking for an excuse to work on our SDKs! \n\nCurrently, we have SDKs in [python](https://github.com/Unbabel/unbabel-py), [ruby](https://github.com/Unbabel/unbabel-ruby), and [php](https://github.com/Unbabel/unbabel-php).\n\nIn your [Unbabel Dashboard](https://unbabel.com/customer/dashboard/api_access/) make a note of your production username and API key.\n\nUsing these credentials and your SDK you are now ready to fully integrate Unbabel into your application or service.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Python\"\n}\n[/block]\nThis is the most developed and maintained repo since we use python here at Unbabel and make heavy use of this SDK.\n\n## Installation\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"pip install unbabel-py\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n# import it and get set up\n\nDo this before all the following examples\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"from unbabel.api import UnbabelApi\\n\\nuapi = UnbabelApi(unbabel_username, unbabel_api_key, \\n                  sandbox=in_test_mode)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n# post single translation\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"to_translate = 'This is a test'\\ntarget_language = 'pt'\\ncallback_url = 'http://my_awesome_app.com/unbabel_callback/'\\n\\nuapi.post_translations(text=to_translate, target_language=target_language,\\n                       callback_url=callback_url)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Ruby\"\n}\n[/block]\nWe created the ruby SDK in collaboration with [jobbox](jobbox.io) with two [/translation/](doc:tapiv2translation) endpoints. They are on Rails, so the following is the examples are from their use case.\n\n## Installation\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# place this in your Gemfile\\n\\ngem 'unbabel-ruby', github: 'Unbabel/unbabel-ruby', require:’unbabel’\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n## Import and get set up\n\nBefore requesting translation, get credentials and instantiate \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# No need to import, the entry in the Gemfile takes care of it\\n# as long as you are in a Rails project\\n\\n# In production, you will want to keep the username / password\\n# as an environment variable or in a config file\\nusername = ENV['UNBABEL_USER_ID']\\napikey = ENV['UNBABEL_API_KEY']\\n\\nub = Unbabel.new(username, apikey)\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n## Request a translation\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"to_translate = 'This is a test'\\ntarget_language = 'pt'\\n\\nub.post_translations(to_translate, target_language, \\n  \\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\ttext_format: :html, \\n  \\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\tcallback_url: callback_url)\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n## Check on the status of the translation\n\nUsing the translation id from the initial request, check on the status.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"response = ub.query_translation(uid)\\n# This JSON.parse calls should probably be done from within\\n# the SDK so you don't have to use it every time.\\npayload = JSON.parse response.body\\nstatus = payload['status'].to_sym\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"PHP\"\n}\n[/block]\nThis SDK is in very early-stage development. Suggestions are welcome!\n\n## Installation\n\nYou can install via composer with the following `composer.json` file\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"require\\\": {\\n        \\\"unbabel/unbabel-php\\\": \\\"dev-master\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Import and setup\n\nIf installed via composer, require and instantiate\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\nrequire 'vendor/autoload.php';\\n\\n$unbabel_username = getenv('UNBABEL_USERNAME');\\n$unbabel_apikey = getenv('UNBABEL_APIKEY');\\n\\n$unbabel = new Unbabel($unbabel_username, $unbabel_apikey, \\n                       $sandbox = false);\\n\\n?>\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\n## Now request a translation\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\n$text = 'This is a test';\\n$target_language = 'pt';\\n\\n$resp = $unbabel->submitTranslation($text, $target_language);\\n\\n?>\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]","createdAt":"2015-01-09T12:36:42.204Z","githubsync":"","hidden":false,"link_external":false,"slug":"sdks","title":"SDKs","__v":8,"category":"54afb7170cf42a0b001d5bf1","order":6,"parentDoc":null,"project":"54ad6c769219922100751763","user":"54ad6c239219922100751762","api":{"auth":"required","params":[],"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","url":""},"link_url":"","updates":[],"excerpt":"","sync_unique":"","type":"basic","childrenPages":[]}

SDKs


We currently have several SDKs in various stages of development. If your preferred language's SDK needs development or does not exist, please get in touch with us at api@unbabel.com! We are always looking for an excuse to work on our SDKs! Currently, we have SDKs in [python](https://github.com/Unbabel/unbabel-py), [ruby](https://github.com/Unbabel/unbabel-ruby), and [php](https://github.com/Unbabel/unbabel-php). In your [Unbabel Dashboard](https://unbabel.com/customer/dashboard/api_access/) make a note of your production username and API key. Using these credentials and your SDK you are now ready to fully integrate Unbabel into your application or service. [block:api-header] { "type": "basic", "title": "Python" } [/block] This is the most developed and maintained repo since we use python here at Unbabel and make heavy use of this SDK. ## Installation [block:code] { "codes": [ { "code": "pip install unbabel-py", "language": "python" } ] } [/block] # import it and get set up Do this before all the following examples [block:code] { "codes": [ { "code": "from unbabel.api import UnbabelApi\n\nuapi = UnbabelApi(unbabel_username, unbabel_api_key, \n sandbox=in_test_mode)", "language": "python" } ] } [/block] # post single translation [block:code] { "codes": [ { "code": "to_translate = 'This is a test'\ntarget_language = 'pt'\ncallback_url = 'http://my_awesome_app.com/unbabel_callback/'\n\nuapi.post_translations(text=to_translate, target_language=target_language,\n callback_url=callback_url)", "language": "python" } ] } [/block] [block:api-header] { "type": "basic", "title": "Ruby" } [/block] We created the ruby SDK in collaboration with [jobbox](jobbox.io) with two [/translation/](doc:tapiv2translation) endpoints. They are on Rails, so the following is the examples are from their use case. ## Installation [block:code] { "codes": [ { "code": "# place this in your Gemfile\n\ngem 'unbabel-ruby', github: 'Unbabel/unbabel-ruby', require:’unbabel’", "language": "ruby" } ] } [/block] ## Import and get set up Before requesting translation, get credentials and instantiate [block:code] { "codes": [ { "code": "# No need to import, the entry in the Gemfile takes care of it\n# as long as you are in a Rails project\n\n# In production, you will want to keep the username / password\n# as an environment variable or in a config file\nusername = ENV['UNBABEL_USER_ID']\napikey = ENV['UNBABEL_API_KEY']\n\nub = Unbabel.new(username, apikey)", "language": "ruby" } ] } [/block] ## Request a translation [block:code] { "codes": [ { "code": "to_translate = 'This is a test'\ntarget_language = 'pt'\n\nub.post_translations(to_translate, target_language, \n \t\t\t\t\t\t\t\t\t\t\t\t\t\t\ttext_format: :html, \n \t\t\t\t\t\t\t\t\t\t\t\t\t\t\tcallback_url: callback_url)", "language": "ruby" } ] } [/block] ## Check on the status of the translation Using the translation id from the initial request, check on the status. [block:code] { "codes": [ { "code": "response = ub.query_translation(uid)\n# This JSON.parse calls should probably be done from within\n# the SDK so you don't have to use it every time.\npayload = JSON.parse response.body\nstatus = payload['status'].to_sym", "language": "ruby" } ] } [/block] [block:api-header] { "type": "basic", "title": "PHP" } [/block] This SDK is in very early-stage development. Suggestions are welcome! ## Installation You can install via composer with the following `composer.json` file [block:code] { "codes": [ { "code": "{\n \"require\": {\n \"unbabel/unbabel-php\": \"dev-master\"\n }\n}", "language": "json" } ] } [/block] ## Import and setup If installed via composer, require and instantiate [block:code] { "codes": [ { "code": "<?php\nrequire 'vendor/autoload.php';\n\n$unbabel_username = getenv('UNBABEL_USERNAME');\n$unbabel_apikey = getenv('UNBABEL_APIKEY');\n\n$unbabel = new Unbabel($unbabel_username, $unbabel_apikey, \n $sandbox = false);\n\n?>", "language": "php" } ] } [/block] ## Now request a translation [block:code] { "codes": [ { "code": "<?php\n\n$text = 'This is a test';\n$target_language = 'pt';\n\n$resp = $unbabel->submitTranslation($text, $target_language);\n\n?>", "language": "php" } ] } [/block]
We currently have several SDKs in various stages of development. If your preferred language's SDK needs development or does not exist, please get in touch with us at api@unbabel.com! We are always looking for an excuse to work on our SDKs! Currently, we have SDKs in [python](https://github.com/Unbabel/unbabel-py), [ruby](https://github.com/Unbabel/unbabel-ruby), and [php](https://github.com/Unbabel/unbabel-php). In your [Unbabel Dashboard](https://unbabel.com/customer/dashboard/api_access/) make a note of your production username and API key. Using these credentials and your SDK you are now ready to fully integrate Unbabel into your application or service. [block:api-header] { "type": "basic", "title": "Python" } [/block] This is the most developed and maintained repo since we use python here at Unbabel and make heavy use of this SDK. ## Installation [block:code] { "codes": [ { "code": "pip install unbabel-py", "language": "python" } ] } [/block] # import it and get set up Do this before all the following examples [block:code] { "codes": [ { "code": "from unbabel.api import UnbabelApi\n\nuapi = UnbabelApi(unbabel_username, unbabel_api_key, \n sandbox=in_test_mode)", "language": "python" } ] } [/block] # post single translation [block:code] { "codes": [ { "code": "to_translate = 'This is a test'\ntarget_language = 'pt'\ncallback_url = 'http://my_awesome_app.com/unbabel_callback/'\n\nuapi.post_translations(text=to_translate, target_language=target_language,\n callback_url=callback_url)", "language": "python" } ] } [/block] [block:api-header] { "type": "basic", "title": "Ruby" } [/block] We created the ruby SDK in collaboration with [jobbox](jobbox.io) with two [/translation/](doc:tapiv2translation) endpoints. They are on Rails, so the following is the examples are from their use case. ## Installation [block:code] { "codes": [ { "code": "# place this in your Gemfile\n\ngem 'unbabel-ruby', github: 'Unbabel/unbabel-ruby', require:’unbabel’", "language": "ruby" } ] } [/block] ## Import and get set up Before requesting translation, get credentials and instantiate [block:code] { "codes": [ { "code": "# No need to import, the entry in the Gemfile takes care of it\n# as long as you are in a Rails project\n\n# In production, you will want to keep the username / password\n# as an environment variable or in a config file\nusername = ENV['UNBABEL_USER_ID']\napikey = ENV['UNBABEL_API_KEY']\n\nub = Unbabel.new(username, apikey)", "language": "ruby" } ] } [/block] ## Request a translation [block:code] { "codes": [ { "code": "to_translate = 'This is a test'\ntarget_language = 'pt'\n\nub.post_translations(to_translate, target_language, \n \t\t\t\t\t\t\t\t\t\t\t\t\t\t\ttext_format: :html, \n \t\t\t\t\t\t\t\t\t\t\t\t\t\t\tcallback_url: callback_url)", "language": "ruby" } ] } [/block] ## Check on the status of the translation Using the translation id from the initial request, check on the status. [block:code] { "codes": [ { "code": "response = ub.query_translation(uid)\n# This JSON.parse calls should probably be done from within\n# the SDK so you don't have to use it every time.\npayload = JSON.parse response.body\nstatus = payload['status'].to_sym", "language": "ruby" } ] } [/block] [block:api-header] { "type": "basic", "title": "PHP" } [/block] This SDK is in very early-stage development. Suggestions are welcome! ## Installation You can install via composer with the following `composer.json` file [block:code] { "codes": [ { "code": "{\n \"require\": {\n \"unbabel/unbabel-php\": \"dev-master\"\n }\n}", "language": "json" } ] } [/block] ## Import and setup If installed via composer, require and instantiate [block:code] { "codes": [ { "code": "<?php\nrequire 'vendor/autoload.php';\n\n$unbabel_username = getenv('UNBABEL_USERNAME');\n$unbabel_apikey = getenv('UNBABEL_APIKEY');\n\n$unbabel = new Unbabel($unbabel_username, $unbabel_apikey, \n $sandbox = false);\n\n?>", "language": "php" } ] } [/block] ## Now request a translation [block:code] { "codes": [ { "code": "<?php\n\n$text = 'This is a test';\n$target_language = 'pt';\n\n$resp = $unbabel->submitTranslation($text, $target_language);\n\n?>", "language": "php" } ] } [/block]
{"_id":"54afc0d4ed9ada1400afbf52","link_url":"","parentDoc":null,"sync_unique":"","version":"54afb7160cf42a0b001d5bf0","createdAt":"2015-01-09T11:51:48.744Z","excerpt":"Fetch all language pairs supported by Unbabel.","hidden":false,"isReference":false,"order":0,"project":"54ad6c769219922100751763","updates":["5902a868c669170f006645a1"],"user":"54ad6c239219922100751762","category":"55a8e8e1c8bd450d000dd0ec","githubsync":"","next":{"description":"","pages":[]},"__v":7,"api":{"examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/language_pair/","name":"curl"}]},"method":"get","params":[],"results":{"codes":[{"language":"json","code":"{\n  \"objects\": [\n  \t{\n      \"lang_pair\": {\n       \"source_language\": {\n         \"name\": \"Portuguese\", \n         \"shortname\": \"pt\"\n       }, \n      \"target_language\": {\n        \"name\": \"English\", \n        \"shortname\": \"en\"}\n      }\n    }, (...)\n }","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/language_pair/","auth":"required"},"body":"You can use this call to verify if the languages of the translation you are about to request are supported by Unbabel. If they are, you can use the shortnames as the `source_language` and `target_language` fields in the `/translation/` resource.","title":"/language_pair/","link_external":false,"slug":"language_pair","type":"get","childrenPages":[]}

get/language_pair/

Fetch all language pairs supported by Unbabel.

You can use this call to verify if the languages of the translation you are about to request are supported by Unbabel. If they are, you can use the shortnames as the `source_language` and `target_language` fields in the `/translation/` resource.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



You can use this call to verify if the languages of the translation you are about to request are supported by Unbabel. If they are, you can use the shortnames as the `source_language` and `target_language` fields in the `/translation/` resource.
{"_id":"55a8b68229d10b2100779fbe","githubsync":"","hidden":false,"project":"54ad6c769219922100751763","sync_unique":"","title":"/translation/","user":"54ad6c239219922100751762","category":"55a8b603f36b3f2d00f12158","excerpt":"Create translation jobs","link_external":false,"next":{"description":"","pages":[]},"parentDoc":null,"updates":["56798d35239fac0d00c7e00b"],"__v":6,"createdAt":"2015-07-17T08:02:10.013Z","editedParams":true,"link_url":"","slug":"translation","type":"post","version":"54afb7160cf42a0b001d5bf0","api":{"url":"/translation/","auth":"required","examples":{"codes":[{"name":"","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X POST https://api.unbabel.com/tapi/v2/translation/ \\\n        -d '{\n                \"text\": \"Text to be translated\",\n                \"target_language\": \"pt\"\n            }'","language":"shell"}]},"method":"post","params":[{"_id":"55a8b68229d10b2100779fbf","ref":"","in":"body","required":true,"desc":"UTF-8 encoding is preferred.","default":"","type":"string","name":"text"},{"_id":"55a8b773f36b3f2d00f12166","ref":"","in":"body","required":true,"desc":"Language shortname. See the language_pair endpoint for available languages and their shortnames.","default":"","type":"string","name":"target_language"},{"_id":"55a8b6d4402f330d00a373da","ref":"","in":"body","required":false,"desc":"If not supplied will be auto-detected. Language detection is not 100% accurate so please supply this field if possible!","default":"","type":"string","name":"source_language"},{"_id":"55a8b773f36b3f2d00f12165","ref":"","in":"body","required":false,"desc":"If you already have a translation you want post-edited, use this field.","default":"","type":"string","name":"target_text"},{"_id":"55a8b773f36b3f2d00f1215f","ref":"","in":"body","required":false,"desc":"You can choose from \"text\", \"html\", \"srt\" or \"xliff\"","default":"text","type":"string","name":"text_format"},{"_id":"55a8b773f36b3f2d00f12164","ref":"","in":"body","required":false,"desc":"You can specify an ID for a particular translation. Note that it has to be unique.","default":"","type":"string","name":"uid"},{"_id":"55a8b773f36b3f2d00f12163","ref":"","in":"body","required":false,"desc":"If supplied we will POST the translation back to this URL when it is complete.","default":"","type":"string","name":"callback_url"},{"_id":"596fd2f62decf000429d875f","ref":"","in":"body","required":false,"desc":"Enter a uid of a Brand or omit to use the brand default","default":"","type":"string","name":"brand"},{"_id":"55a8b773f36b3f2d00f12162","ref":"","in":"body","required":false,"desc":"See tone endpoint for list of available tones. Omit this field to use brand value.","default":"","type":"string","name":"tone"},{"_id":"55a8b773f36b3f2d00f12161","ref":"","in":"body","required":false,"desc":"These instructions will be shown to Editors while they are working on your translation. Omit this field to use brand value.","default":"","type":"string","name":"instructions"},{"_id":"55a8b773f36b3f2d00f12160","ref":"","in":"body","required":false,"desc":"See topic endpoint for list of possible topics.","default":"","type":"array_string","name":"topics"}],"results":{"codes":[{"status":201,"name":"","code":"{\n    \"balance\": 2784.0, \n    \"client\": \"username\", \n    \"price\": 8.0, \n    \"source_language\": \"en\", \n    \"status\": \"new\", \n    \"target_language\": \"pt\", \n    \"text\": \"Text to be translated\", \n    \"text_format\": \"text\", \n    \"uid\": \"9a86cf619f\"\n}","language":"json"},{"code":"{}","language":"json","status":400,"name":""}]},"settings":""},"editedParams2":true,"isReference":false,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Preserving variables\"\n}\n[/block]\nWhen sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- If this was your content -->\\n<p>Hello, world, my name is {{ name }}</p>\\n\\n\\n<!-- This is how it should look like before sending it to Unbabel -->\\n<p>Hello world, my name is <span class=\\\"notranslate\\\" origval=\\\"{{ name }}\\\">John Smith</span></p>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe tag used to wrap the variable can be of any type, the only requirements are the two attributes.\n\nIn order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"class\",\n    \"0-1\": \"The class of the tag must be **notranslate**. Anything else won't work.\",\n    \"1-0\": \"origval\",\n    \"1-1\": \"This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]","childrenPages":[]}

post/translation/

Create translation jobs

Body Params

text:
required
string
UTF-8 encoding is preferred.
target_language:
required
string
Language shortname. See the language_pair endpoint for available languages and their shortnames.
source_language:
string
If not supplied will be auto-detected. Language detection is not 100% accurate so please supply this field if possible!
target_text:
string
If you already have a translation you want post-edited, use this field.
text_format:
stringtext
You can choose from "text", "html", "srt" or "xliff"
uid:
string
You can specify an ID for a particular translation. Note that it has to be unique.
callback_url:
string
If supplied we will POST the translation back to this URL when it is complete.
brand:
string
Enter a uid of a Brand or omit to use the brand default
tone:
string
See tone endpoint for list of available tones. Omit this field to use brand value.
instructions:
string
These instructions will be shown to Editors while they are working on your translation. Omit this field to use brand value.
topics:
array of strings
See topic endpoint for list of possible topics.
[block:api-header] { "type": "basic", "title": "Preserving variables" } [/block] When sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way. [block:code] { "codes": [ { "code": "<!-- If this was your content -->\n<p>Hello, world, my name is {{ name }}</p>\n\n\n<!-- This is how it should look like before sending it to Unbabel -->\n<p>Hello world, my name is <span class=\"notranslate\" origval=\"{{ name }}\">John Smith</span></p>", "language": "html" } ] } [/block] The tag used to wrap the variable can be of any type, the only requirements are the two attributes. In order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "class", "0-1": "The class of the tag must be **notranslate**. Anything else won't work.", "1-0": "origval", "1-1": "This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values." }, "cols": 2, "rows": 2 } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "type": "basic", "title": "Preserving variables" } [/block] When sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way. [block:code] { "codes": [ { "code": "<!-- If this was your content -->\n<p>Hello, world, my name is {{ name }}</p>\n\n\n<!-- This is how it should look like before sending it to Unbabel -->\n<p>Hello world, my name is <span class=\"notranslate\" origval=\"{{ name }}\">John Smith</span></p>", "language": "html" } ] } [/block] The tag used to wrap the variable can be of any type, the only requirements are the two attributes. In order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "class", "0-1": "The class of the tag must be **notranslate**. Anything else won't work.", "1-0": "origval", "1-1": "This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values." }, "cols": 2, "rows": 2 } [/block]
{"_id":"55a8c604c8bd450d000dd05a","hidden":false,"parentDoc":null,"type":"patch","__v":2,"api":{"settings":"","url":"/translation/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X PATCH https://api.unbabel.com/tapi/v2/translation/ \\\n        -d '{\n        \t\t\t\t\"objects\": [\n                \t\t{\n        \t            \t\"text\": \"Text to be translated\",\n\t\t\t\t                \"target_language\": \"pt\" \n                    },{\n        \t            \t\"text\": \"Other text to be translated\",\n\t\t\t\t                \"target_language\": \"pt\" \n                    }\n                ]\n            }'","name":""}]},"method":"patch","params":[{"_id":"55a8c7d2cf45e1390093f19a","default":"","desc":"An array of dictionaries with the same data as a POST Request to /translation/","in":"body","name":"objects","ref":"","required":true,"type":"array_mixed"}],"results":{"codes":[{"status":202,"language":"json","code":"{\n    \"objects\": [\n        {\n            \"balance\": 2754.0, \n            \"client\": \"andreffs18\", \n            \"price\": 8.0, \n            \"source_language\": \"en\", \n            \"status\": \"new\", \n            \"target_language\": \"pt\", \n            \"text\": \"Text to be translated\", \n            \"text_format\": \"text\", \n            \"uid\": \"d185ec9465\"\n        }, \n        {\n            \"balance\": 2746.0, \n            \"client\": \"andreffs18\", \n            \"price\": 10.0, \n            \"source_language\": \"en\", \n            \"status\": \"new\", \n            \"target_language\": \"pt\", \n            \"text\": \"Other text to be translated\", \n            \"text_format\": \"text\", \n            \"uid\": \"547027489f\"\n        }\n    ]\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]}},"body":"","editedParams2":true,"updates":[],"version":"54afb7160cf42a0b001d5bf0","sync_unique":"","title":"/translation/","category":"55a8b603f36b3f2d00f12158","excerpt":"Exactly the same as POST but there is a new top-level key in the request data called \"objects\" which contains an array of translation requests.","githubsync":"","link_url":"","next":{"pages":[],"description":""},"createdAt":"2015-07-17T09:08:20.040Z","editedParams":true,"link_external":false,"order":1,"isReference":false,"project":"54ad6c769219922100751763","slug":"translation-1","user":"54ad6c239219922100751762","childrenPages":[]}

patch/translation/

Exactly the same as POST but there is a new top-level key in the request data called "objects" which contains an array of translation requests.

Body Params

objects:
required
array of mixed
An array of dictionaries with the same data as a POST Request to /translation/

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"56cb4b11245b841300806f13","api":{"settings":"","url":"/translation/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/translation/","name":"Curl (list all)"},{"name":"Curl (filter per target language)","language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://unbabel.com/tapi/v2/translation/?target_language__in=[\"pt\", \"es]"}]},"method":"get","params":[{"_id":"56cb4b11245b841300806f16","default":"","desc":"startswith, endswith, contains","name":":uid","ref":"","required":false,"type":"string","in":"query"},{"in":"query","_id":"55a8d952c8bd450d000dd0b3","default":"","desc":"Acceptable status: \"new\", \"translating\", \"completed\", \"failed\", \"canceled\", \"accepted\", \"rejected\"","name":":status","ref":"","required":false,"type":"string"},{"default":"","desc":"in, nin (Not In), ne (Not Equal)","name":"source_language","ref":"","required":false,"type":"string","in":"query","_id":"56cb4b11245b841300806f15"},{"required":false,"type":"string","in":"query","_id":"56cb4b11245b841300806f14","default":"","desc":"in, nin (Not In), ne (Not Equal)","name":"target_language","ref":""}],"results":{"codes":[{"name":"","code":"{\n    \"meta\": {\n        \"limit\": 20, \n        \"next\": null, \n        \"offset\": 0, \n        \"previous\": null, \n        \"total_count\": 3\n    }, \n    \"objects\": [\n        {\n            \"price\": 10, \n            \"source_language\": \"en\", \n            \"status\": \"new\", \n            \"target_language\": \"pt\", \n            \"text_format\": \"text\", \n            \"uid\": \"30292308e7\"\n        }, (...)\n    ]\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]}},"category":"55a8b603f36b3f2d00f12158","createdAt":"2016-02-22T17:53:21.945Z","slug":"translation-list-update","body":"","order":3,"project":"54ad6c769219922100751763","updates":[],"type":"get","user":"561637e421e9110d007802f9","version":"54afb7160cf42a0b001d5bf0","__v":1,"excerpt":"Get jobs with a specific status","githubsync":"","next":{"description":"","pages":[]},"sync_unique":"","link_external":false,"link_url":"","parentDoc":null,"editedParams":true,"editedParams2":true,"hidden":false,"isReference":false,"title":"/translation/","childrenPages":[]}

get/translation/

Get jobs with a specific status

Query Params

uid:
string
startswith, endswith, contains
status:
string
Acceptable status: "new", "translating", "completed", "failed", "canceled", "accepted", "rejected"
source_language:
string
in, nin (Not In), ne (Not Equal)
target_language:
string
in, nin (Not In), ne (Not Equal)

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"55a8d952c8bd450d000dd0b2","parentDoc":null,"__v":2,"createdAt":"2015-07-17T10:30:42.378Z","isReference":false,"link_url":"","next":{"description":"","pages":[]},"order":4,"user":"54ad6c239219922100751762","link_external":false,"type":"get","editedParams":true,"excerpt":"Get a translation job by its uid","githubsync":"","project":"54ad6c769219922100751763","title":"/translation/:uid/","version":"54afb7160cf42a0b001d5bf0","updates":[],"api":{"settings":"","url":"/translation/:uid/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/translation/:uid/","name":""}]},"method":"get","params":[{"_id":"58dd55d73ca9540f00ef17d2","ref":"","in":"path","required":false,"desc":"UID returned from the original POST or PATCH request","default":"","type":"string","name":":uid"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"balance\": 2682.0, \n    \"client\": \"username\", \n    \"price\": 12.0, \n    \"source_language\": \"en\", \n    \"status\": \"new\", \n    \"target_language\": \"pt\", \n    \"text\": \"The quick brown fox\", \n    \"text_format\": \"text\", \n    \"uid\": \"f2f7a62ca5\"\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]}},"body":"","category":"55a8b603f36b3f2d00f12158","editedParams2":true,"hidden":false,"slug":"translation-detail","sync_unique":"","childrenPages":[]}

get/translation/:uid/

Get a translation job by its uid

Path Params

uid:
string
UID returned from the original POST or PATCH request

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"58dd550915f4150f00839b74","api":{"auth":"required","examples":{"codes":[{"name":"","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X DELETE https://api.unbabel.com/tapi/v2/translation/:uid/","language":"shell"}]},"method":"delete","params":[{"type":"string","name":":uid","_id":"58dd553985a2a02f0005188f","ref":"","in":"path","required":false,"desc":"UID returned from the original POST or PATCH request","default":""}],"results":{"codes":[{"name":"","code":"","language":"text","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","url":"/translation/:uid/"},"isReference":false,"link_url":"","project":"54ad6c769219922100751763","slug":"translation-cancel","sync_unique":"","excerpt":"Cancel a translation request","hidden":false,"parentDoc":null,"user":"561637e421e9110d007802f9","__v":1,"body":"","link_external":false,"next":{"pages":[],"description":""},"order":5,"type":"delete","updates":[],"version":"54afb7160cf42a0b001d5bf0","category":"55a8b603f36b3f2d00f12158","createdAt":"2017-03-30T18:57:13.840Z","githubsync":"","title":"/translation/:uid/","childrenPages":[]}

delete/translation/:uid/

Cancel a translation request

Path Params

uid:
string
UID returned from the original POST or PATCH request

Definition

{{ api_url }}{{ page_api_url }}

Examples



{"_id":"580f4f217567d72500498700","link_url":"","parentDoc":null,"updates":[],"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Preserving variables\"\n}\n[/block]\nWhen sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- If this was your content -->\\n<p>Hello, world, my name is {{ name }}</p>\\n\\n\\n<!-- This is how it should look like before sending it to Unbabel -->\\n<p>Hello world, my name is <span class=\\\"notranslate\\\" origval=\\\"{{ name }}\\\">John Smith</span></p>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe tag used to wrap the variable can be of any type, the only requirements are the two attributes.\n\nIn order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"class\",\n    \"0-1\": \"The class of the tag must be **notranslate**. Anything else won't work.\",\n    \"1-0\": \"origval\",\n    \"1-1\": \"This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]","githubsync":"","slug":"mt_translation","api":{"auth":"required","examples":{"codes":[{"name":"","code":"#!/bin/bash\ncurl \\\n  -H \"Authorization: ApiKey username:apikey\" \\\n  -H \"Content-Type: application/json\" \\\n  -X POST https://api.unbabel.com/tapi/v2/mt_translation/ \\\n  -d '{ \"text\": \"Hello, world\", \"target_language\": \"pt\"}'","language":"shell"}]},"method":"post","params":[{"desc":"UTF-8 encoding is preferred.","default":"","type":"string","name":"text","_id":"55a8b68229d10b2100779fbf","ref":"","in":"body","required":true},{"_id":"55a8b773f36b3f2d00f12166","ref":"","in":"body","required":true,"desc":"Language shortname. See the language_pair endpoint for available languages and their shortnames.","default":"","type":"string","name":"target_language"},{"name":"source_language","_id":"55a8b6d4402f330d00a373da","ref":"","in":"body","required":false,"desc":"If not supplied will be auto-detected. Language detection is not 100% accurate so please supply this field if possible!","default":"","type":"string"},{"type":"string","name":"text_format","_id":"55a8b773f36b3f2d00f1215f","ref":"","in":"body","required":false,"desc":"You can choose from \"text\", \"html\", \"srt\" or \"xliff\"","default":"text"},{"required":false,"desc":"You can specify an ID for a particular translation. Note that it has to be unique.","default":"","type":"string","name":"uid","_id":"55a8b773f36b3f2d00f12164","ref":"","in":"body"},{"type":"string","name":"callback_url","_id":"55a8b773f36b3f2d00f12163","ref":"","in":"body","required":false,"desc":"If supplied we will POST the translation back to this URL when it is complete.","default":""},{"desc":"See tone endpoint for list of available tones.","default":"","type":"string","name":"tone","_id":"55a8b773f36b3f2d00f12162","ref":"","in":"body","required":false},{"name":"topics","_id":"55a8b773f36b3f2d00f12160","ref":"","in":"body","required":false,"desc":"See topic endpoint for list of possible topics.","default":"","type":"array_string"}],"results":{"codes":[{"status":201,"name":"","code":"{\n\t\t\"origin\": \"api\",\n  \t\"source_language\": \"en\",\n  \t\"status\": \"machine_translate_in_progress\",\n  \t\"target_language\": \"pt\",\n  \t\"text\": \"Hello, world\",\n  \t\"text_format\": \"text\",\n  \t\"uid\": \"329165fca4\"\n}","language":"json"},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","url":"/mt_translation/"},"createdAt":"2016-10-25T12:25:05.084Z","hidden":false,"isReference":false,"next":{"description":"","pages":[]},"title":"/mt_translation/","type":"post","version":"54afb7160cf42a0b001d5bf0","__v":2,"category":"55a8b603f36b3f2d00f12158","excerpt":"Create machine translation only jobs","link_external":false,"order":6,"project":"54ad6c769219922100751763","sync_unique":"","user":"57eaf88543d2780e008e7a87","childrenPages":[]}

post/mt_translation/

Create machine translation only jobs

Body Params

text:
required
string
UTF-8 encoding is preferred.
target_language:
required
string
Language shortname. See the language_pair endpoint for available languages and their shortnames.
source_language:
string
If not supplied will be auto-detected. Language detection is not 100% accurate so please supply this field if possible!
text_format:
stringtext
You can choose from "text", "html", "srt" or "xliff"
uid:
string
You can specify an ID for a particular translation. Note that it has to be unique.
callback_url:
string
If supplied we will POST the translation back to this URL when it is complete.
tone:
string
See tone endpoint for list of available tones.
topics:
array of strings
See topic endpoint for list of possible topics.
[block:api-header] { "type": "basic", "title": "Preserving variables" } [/block] When sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way. [block:code] { "codes": [ { "code": "<!-- If this was your content -->\n<p>Hello, world, my name is {{ name }}</p>\n\n\n<!-- This is how it should look like before sending it to Unbabel -->\n<p>Hello world, my name is <span class=\"notranslate\" origval=\"{{ name }}\">John Smith</span></p>", "language": "html" } ] } [/block] The tag used to wrap the variable can be of any type, the only requirements are the two attributes. In order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "class", "0-1": "The class of the tag must be **notranslate**. Anything else won't work.", "1-0": "origval", "1-1": "This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values." }, "cols": 2, "rows": 2 } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "type": "basic", "title": "Preserving variables" } [/block] When sending translation jobs in HTML or XLIFF sometimes you have variables that must be preserved. To do that the variables have to be wrapped in a specific way. [block:code] { "codes": [ { "code": "<!-- If this was your content -->\n<p>Hello, world, my name is {{ name }}</p>\n\n\n<!-- This is how it should look like before sending it to Unbabel -->\n<p>Hello world, my name is <span class=\"notranslate\" origval=\"{{ name }}\">John Smith</span></p>", "language": "html" } ] } [/block] The tag used to wrap the variable can be of any type, the only requirements are the two attributes. In order to give more context to our translators the content inside the tag with the class **notranslate** should be an example of what the variable is, as in the example above. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "class", "0-1": "The class of the tag must be **notranslate**. Anything else won't work.", "1-0": "origval", "1-1": "This attribute saves the variable. After the translation is complete the content inside tags with **notranslate** attribute is replaced with the correspondent **origval** values." }, "cols": 2, "rows": 2 } [/block]
{"_id":"580f503a7567d72500498701","slug":"mt_translation-1","title":"/mt_translation/","user":"57eaf88543d2780e008e7a87","githubsync":"","order":7,"parentDoc":null,"project":"54ad6c769219922100751763","body":"","excerpt":"Get machine translation jobs with a specific status","link_url":"","type":"get","updates":[],"__v":1,"category":"55a8b603f36b3f2d00f12158","createdAt":"2016-10-25T12:29:46.116Z","link_external":false,"next":{"description":"","pages":[]},"api":{"method":"get","params":[{"desc":"startswith, endswith, contains","default":"","type":"string","name":":uid","_id":"56cb4b11245b841300806f16","ref":"","in":"query","required":false},{"_id":"55a8d952c8bd450d000dd0b3","ref":"","in":"query","required":false,"desc":"Acceptable status: \"new\", \"translating\", \"completed\", \"failed\", \"canceled\", \"accepted\", \"rejected\"","default":"","type":"string","name":":status"},{"name":"source_language","_id":"56cb4b11245b841300806f15","ref":"","in":"query","required":false,"desc":"in, nin (Not In), ne (Not Equal)","default":"","type":"string"},{"ref":"","in":"query","required":false,"desc":"in, nin (Not In), ne (Not Equal)","default":"","type":"string","name":"target_language","_id":"56cb4b11245b841300806f14"}],"results":{"codes":[{"status":200,"name":"","code":"{\n    \"meta\": {\n        \"limit\": 20, \n        \"next\": null, \n        \"offset\": 0, \n        \"previous\": null, \n        \"total_count\": 3\n    }, \n    \"objects\": [\n        {\n            \"price\": 10, \n            \"source_language\": \"en\", \n            \"status\": \"new\", \n            \"target_language\": \"pt\", \n            \"text_format\": \"text\", \n            \"uid\": \"30292308e7\"\n        }, (...)\n    ]\n}","language":"json"},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","url":"/mt_translation/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl \\\n  -H \"Authorization: ApiKey username:apikey\" \\\n  -X GET https://api.unbabel.com/tapi/v2/mt_translation/329165","name":"Curl (list all)"},{"name":"Curl (filter per target language)","language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://unbabel.com/tapi/v2/translation/?target_language__in=[\"pt\", \"es]"}]}},"hidden":false,"isReference":false,"sync_unique":"","version":"54afb7160cf42a0b001d5bf0","childrenPages":[]}

get/mt_translation/

Get machine translation jobs with a specific status

Query Params

uid:
string
startswith, endswith, contains
status:
string
Acceptable status: "new", "translating", "completed", "failed", "canceled", "accepted", "rejected"
source_language:
string
in, nin (Not In), ne (Not Equal)
target_language:
string
in, nin (Not In), ne (Not Equal)

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"580f51c833021619006cbc72","api":{"params":[{"default":"","desc":"Uid returned from the original POST request","in":"query","name":":uid","ref":"","required":true,"type":"string","_id":"55a8d952c8bd450d000dd0b3"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"balance\": 2682.0, \n    \"client\": \"username\", \n    \"price\": 12.0, \n    \"source_language\": \"en\", \n    \"status\": \"new\", \n    \"target_language\": \"pt\", \n    \"text\": \"The quick brown fox\", \n    \"text_format\": \"text\", \n    \"uid\": \"f2f7a62ca5\"\n}","name":""},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","url":"/mt_translation/:uid/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/translation/:uid/","name":""}]},"method":"get"},"body":"","link_url":"","parentDoc":null,"title":"/mt_translation/:uid/","__v":1,"createdAt":"2016-10-25T12:36:24.763Z","githubsync":"","order":8,"sync_unique":"","updates":[],"version":"54afb7160cf42a0b001d5bf0","category":"55a8b603f36b3f2d00f12158","hidden":false,"isReference":false,"link_external":false,"next":{"pages":[],"description":""},"user":"57eaf88543d2780e008e7a87","excerpt":"Get a machine translation job by its uid","project":"54ad6c769219922100751763","slug":"mt_translationuid","type":"get","childrenPages":[]}

get/mt_translation/:uid/

Get a machine translation job by its uid

Query Params

uid:
required
string
Uid returned from the original POST request

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"55a8e3b027a17d210052518c","editedParams":true,"editedParams2":true,"isReference":false,"link_url":"","user":"54ad6c239219922100751762","updates":[],"createdAt":"2015-07-17T11:14:56.413Z","link_external":false,"project":"54ad6c769219922100751763","slug":"report","type":"post","parentDoc":null,"api":{"auth":"required","examples":{"codes":[{"name":"","language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X POST https://api.unbabel.com/tapi/v2/report/ \\\n        -d '{\n                \"uid\": \"3b0f609330\",\n                \"comment\": \"This translation has a few mistakes, I want to report it\",\n                \"callback_url\": \"http://your-cool-app.com/unbabel_callback/\",\n                \"types\": [\"grammar\", \"spelling\", \"inconsistencies\", \"missing_text\", \"other\"]\n            }'"}]},"method":"post","params":[{"in":"body","name":"uid","ref":"","required":true,"type":"string","_id":"55a8e3b027a17d2100525190","default":"","desc":"UID of the job that you want report"},{"default":"","desc":"Comment explaining why this job is being reported","in":"body","name":"comment","ref":"","required":true,"type":"string","_id":"55a8e3b027a17d210052518f"},{"desc":"One or more (up to five) types of possible errors with this report. You can choose from the array in the example","in":"body","name":"type","ref":"","required":true,"type":"array_string","_id":"55a8e3b027a17d210052518e","default":""},{"in":"body","name":"callback_url","ref":"","required":true,"type":"string","_id":"55a8e3b027a17d210052518d","default":"","desc":"URL to call to receive a notification when an Editor replies to the report"}],"results":{"codes":[{"status":201,"name":"","code":"{\n  \"created\": \"2015-07-10T11:10:12.686000\", \n  \"changed\": \"2015-07-10T14:28:02.825000\", \n  \"comments\": [\n    {\n      \"commenter\": {\n        \"name\": \"Alice Wonder\", \n        \"picture_url\": \"https://secure.gravatar.com/avatar/(...)\", \n        \"username\": \"alice\"\n      }, \n      \"created\": \"6 hours ago\", \n      \"event\": \"job_reported\", \n      \"text\": \"This translation has a few mistakes, I want to report it\"\n    },\n  ], \n  \"editor\": \"albuquerque.a.andre\", \n  \"uid\": \"3b0f609330\", \n  \"report_id\": \"55a3a1e7421aa9e1c4fb880d\", \n  \"status\": \"open\", \n  \"types\": [\n    \"grammar\", \"spelling\", \"inconsistencies\", \"missing_text\", \"other\"\n  ]\n}","language":"json"},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","url":"/report/"},"category":"55a8e22e27a17d2100525187","excerpt":"Allows you to report a job because of possible translation mistakes","hidden":false,"order":0,"sync_unique":"","title":"/report/","version":"54afb7160cf42a0b001d5bf0","__v":1,"body":"","githubsync":"","next":{"description":"","pages":[]},"childrenPages":[]}

post/report/

Allows you to report a job because of possible translation mistakes

Body Params

uid:
required
string
UID of the job that you want report
comment:
required
string
Comment explaining why this job is being reported
type:
required
array of strings
One or more (up to five) types of possible errors with this report. You can choose from the array in the example
callback_url:
required
string
URL to call to receive a notification when an Editor replies to the report

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"55a39aca5f54460d000d4c96","__v":2,"isReference":false,"order":1,"api":{"auth":"required","examples":{"codes":[{"code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/report/:report_id \\","language":"shell","name":null}]},"method":"get","params":[{"desc":"ID of the report that you want to get information about","in":"query","name":":report_id","ref":"","required":true,"type":"string","_id":"55a39b165f54460d000d4c9a","default":""}],"results":{"codes":[{"code":"{\n  \"changed\": \"2015-07-10T14:28:02.825000\", \n  \"comments\": [\n    {\n      \"commenter\": {\n        \"name\": \"Alice Wonder\", \n        \"picture_url\": \"https://secure.gravatar.com/avatar/(...)\", \n        \"username\": \"alice\"\n      }, \n      \"created\": \"6 hours ago\", \n      \"event\": \"job_reported\", \n      \"text\": \"This job has a few translation mistakes, I want to report it\"\n    }\n  ], \n  \"created\": \"2015-07-10T11:10:12.686000\", \n  \"editor\": \"albuquerque.a.andre\", \n  \"uid\": \"3b0f609330\", \n  \"report_id\": \"55a3a1e7421aa9e1c4fb880d\", \n  \"status\": \"open\", \n  \"types\": [\n    \"grammar\", \"spelling\", \"inconsistencies\", \"missing_text\", \"other\"\n  ]\n}","language":"json","status":200,"name":""},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","url":"/report/:report_id/"},"createdAt":"2015-07-13T11:02:34.273Z","editedParams":true,"excerpt":"Get a job report","hidden":false,"parentDoc":null,"sync_unique":"","category":"55a8e22e27a17d2100525187","link_external":false,"next":{"description":"","pages":[]},"slug":"get-reportuid","type":"get","user":"54ad6c239219922100751762","body":"","editedParams2":true,"githubsync":"","link_url":"","project":"54ad6c769219922100751763","title":"/report/:report_id/","updates":[],"version":"54afb7160cf42a0b001d5bf0","childrenPages":[]}

get/report/:report_id/

Get a job report

Query Params

report_id:
required
string
ID of the report that you want to get information about

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"55a39f7f912a6e2300882c1f","title":"/report/:report_id/","version":"54afb7160cf42a0b001d5bf0","category":"55a8e22e27a17d2100525187","createdAt":"2015-07-13T11:22:39.534Z","githubsync":"","isReference":false,"link_url":"","parentDoc":null,"api":{"url":"/report/:report_id/","auth":"required","examples":{"codes":[{"code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X PATCH https://api.unbabel.com/tapi/v2/report/:report_id \\\n        -d '{\n                \"comment\": \"It now looks better but there is still a mistake\",\n            }'","name":"","language":"shell"}]},"method":"patch","params":[{"desc":"The ID of the report that you want to add a comment as a customer","in":"path","name":"report_id","ref":"","required":true,"type":"string","_id":"55a3a0b2912a6e2300882c22","default":""},{"in":"body","name":"comment","ref":"","required":true,"type":"string","_id":"55a3a0b2912a6e2300882c21","default":"","desc":"Comment to add to the report"}],"results":{"codes":[{"name":"","status":202,"language":"json","code":"{\n  \"changed\": \"2015-07-10T14:28:02.825000\", \n  \"comments\": [\n    {\n      \"commenter\": {\n        \"name\": \"Alice Wonder\", \n        \"picture_url\": \"https://secure.gravatar.com/avatar/(...)\", \n        \"username\": \"alice\"\n      }, \n      \"created\": \"6 hours ago\", \n      \"event\": \"job_reported\", \n      \"text\": \"This job has a few translation mistakes, I want to report it\"\n    }, \n    {\n      \"commenter\": {\n        \"name\": \"Alice Wonder\", \n        \"picture_url\": \"https://secure.gravatar.com/avatar/(...)\", \n        \"username\": \"alice\"\n      }, \n      \"created\": \"6 hours ago\", \n      \"event\": \"customer_comment\", \n      \"text\": \"It now looks better but there is still a mistake\"\n    }\n  ], \n  \"created\": \"2015-07-10T11:10:12.686000\", \n  \"editor\": \"albuquerque.a.andre\", \n  \"uid\": \"3b0f609330\", \n  \"report_id\": \"55a3a1e7421aa9e1c4fb880d\", \n  \"status\": \"open\", \n  \"types\": [\n    \"grammar\", \"spelling\", \"inconsistencies\", \"missing_text\", \"other\"\n  ]\n}"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":""},"link_external":false,"project":"54ad6c769219922100751763","type":"patch","updates":[],"user":"54ad6c239219922100751762","__v":2,"editedParams2":true,"hidden":false,"next":{"description":"","pages":[]},"slug":"patch-reportuid","sync_unique":"","body":"","editedParams":true,"excerpt":"Add a comment to a particular job report","order":2,"childrenPages":[]}

patch/report/:report_id/

Add a comment to a particular job report

Path Params

report_id:
required
string
The ID of the report that you want to add a comment as a customer

Body Params

comment:
required
string
Comment to add to the report

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"55a3a0f1912a6e2300882c23","link_url":"","parentDoc":null,"updates":[],"user":"54ad6c239219922100751762","editedParams":true,"excerpt":"Accept job after being reported","link_external":false,"project":"54ad6c769219922100751763","type":"patch","version":"54afb7160cf42a0b001d5bf0","__v":2,"body":"","category":"55a8e22e27a17d2100525187","createdAt":"2015-07-13T11:28:49.257Z","isReference":false,"next":{"description":"","pages":[]},"order":3,"slug":"patch-reportuidaccept","title":"/report/:report_id/accept","sync_unique":"","editedParams2":true,"githubsync":"","hidden":false,"api":{"auth":"required","examples":{"codes":[{"name":null,"code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X PATCH https://api.unbabel.com/tapi/v2/report/:report_id/accept/ \\","language":"shell"}]},"method":"patch","params":[{"required":true,"type":"string","_id":"55a3a27d912a6e2300882c26","default":"","desc":"The id of the report that you want to accept","in":"path","name":"report_id","ref":""}],"results":{"codes":[{"status":202,"language":"json","code":"{\n  \"changed\": \"2015-07-13T11:33:22.313000\", \n  \"comments\": [\n    {\n      \"commenter\": {\n        \"name\": \"Alice Wonder\", \n        \"picture_url\": \"https://secure.gravatar.com/avatar/(...)\", \n        \"username\": \"alice\"\n      }, \n      \"created\": \"26 seconds ago\", \n      \"event\": \"job_reported\", \n      \"text\": \"This job has a few translation mistakes, I want to report it\"\n    },\n    {\n      \"commenter\": {\n        \"name\": \"Alice Wonder\", \n        \"picture_url\": \"https://secure.gravatar.com/avatar/(...)\", \n        \"username\": \"alice\"\n      }, \n      \"created\": \"now\", \n      \"event\": \"job_report_approved\", \n      \"text\": \"\"\n    }\n  ], \n  \"created\": \"2015-07-13T11:32:55.580000\", \n  \"editor\": \"a.mattiace\", \n  \"uid\": \"3b0f609330\", \n  \"report_id\": \"55a3a1e7421aa9e1c4fb880d\", \n  \"status\": \"close\", \n  \"types\": [\n    \"grammar\", \"spelling\", \"inconsistencies\", \"missing_text\", \"other\"\n  ]\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/report/:report_id/accept"},"childrenPages":[]}

patch/report/:report_id/accept

Accept job after being reported

Path Params

report_id:
required
string
The id of the report that you want to accept

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"54afc12ea71047160099015a","__v":5,"body":"[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#!/bin/bash\\n\\ncurl -H \\\"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\\\" \\\\\\n     -H \\\"Content-Type: application/json\\\" \\\\\\n     -X GET https://api.unbabel.com/tapi/v2/tone/\\n\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]","link_url":"","sync_unique":"","githubsync":"","isReference":false,"project":"54ad6c769219922100751763","slug":"tone","version":"54afb7160cf42a0b001d5bf0","updates":[],"user":"54ad6c239219922100751762","api":{"params":[],"results":{"codes":[{"code":"{\n  \"objects\": [\n    {\n      \"tone\": {\n       \"description\": \"Informal style\", \n       \"name\": \"Informal\"\n     }\n    },\n    {\n      \"tone\": {\n        \"description\": \"Formal style\", \n        \"name\": \"Formal\"\n      }\n    }\n  ]\n}","name":"","status":200,"language":"json"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/tone/","auth":"required","examples":{"codes":[{"code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/tone/","name":"","language":"shell"}]},"method":"get"},"hidden":false,"link_external":false,"next":{"description":"","pages":[]},"parentDoc":null,"title":"/tone/","category":"55a8e987cf45e1390093f212","createdAt":"2015-01-09T11:53:18.504Z","excerpt":"Get all possible tones that a translation may have. Editors will take the tone into account and possibly use it to change the formality of the translation.","order":0,"type":"get","childrenPages":[]}

get/tone/

Get all possible tones that a translation may have. Editors will take the tone into account and possibly use it to change the formality of the translation.

[block:code] { "codes": [ { "code": "#!/bin/bash\n\ncurl -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -X GET https://api.unbabel.com/tapi/v2/tone/\n", "language": "shell" } ] } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:code] { "codes": [ { "code": "#!/bin/bash\n\ncurl -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -X GET https://api.unbabel.com/tapi/v2/tone/\n", "language": "shell" } ] } [/block]
{"_id":"54afc1a2ed9ada1400afbf56","slug":"topic","sync_unique":"","title":"/topic/","body":"[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#!/bin/bash\\n\\ncurl -H \\\"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\\\" \\\\\\n     -H \\\"Content-Type: application/json\\\" \\\\\\n     -X GET https://unbabel.com/tapi/v2/topic/\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]","category":"55a8e98c27a17d21005251a8","createdAt":"2015-01-09T11:55:14.498Z","githubsync":"","link_url":"","updates":[],"user":"54ad6c239219922100751762","type":"get","version":"54afb7160cf42a0b001d5bf0","api":{"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"objects\": [\n    {\n      \"topic\": {\n        \"name\": \"politics\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"gossip\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"sex & relationships\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"crafts\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"parenting\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"startups\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"tech\"\n      }\n    }, \n    {\n      \"topic\": {\n        \"name\": \"sports\"\n      }\n    }\n  ]\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/topic/","auth":"required","examples":{"codes":[{"language":"shell","code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X GET https://api.unbabel.com/tapi/v2/topic/","name":""}]},"method":"get","params":[]},"isReference":false,"order":0,"project":"54ad6c769219922100751763","__v":5,"excerpt":"Get list of topics that may be applied to a translation. Specifying one of these when POSTing a translation will help Unbabel choose which Editors to assign to the translation based upon their experience.","next":{"description":"","pages":[]},"parentDoc":null,"hidden":false,"link_external":false,"childrenPages":[]}

get/topic/

Get list of topics that may be applied to a translation. Specifying one of these when POSTing a translation will help Unbabel choose which Editors to assign to the translation based upon their experience.

[block:code] { "codes": [ { "code": "#!/bin/bash\n\ncurl -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -X GET https://unbabel.com/tapi/v2/topic/", "language": "shell" } ] } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:code] { "codes": [ { "code": "#!/bin/bash\n\ncurl -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -X GET https://unbabel.com/tapi/v2/topic/", "language": "shell" } ] } [/block]
{"_id":"5539007ef426ca0d003ae42b","editedParams":true,"excerpt":"Count words on a text","link_url":"","project":"54ad6c769219922100751763","order":0,"parentDoc":null,"sync_unique":"","body":"","category":"55a8e9d127a17d21005251a9","githubsync":"","link_external":false,"next":{"description":"","pages":[]},"title":"/wordcount/","createdAt":"2015-04-23T14:23:58.037Z","hidden":false,"user":"54f0cebb7d40be370012d525","type":"post","updates":[],"version":"54afb7160cf42a0b001d5bf0","__v":7,"api":{"params":[{"required":true,"type":"string","_id":"55a8eb30cf45e1390093f21c","default":"","desc":"From where we will be counting all the words","in":"body","name":"text","ref":""}],"results":{"codes":[{"status":201,"language":"json","code":"{\n  \"word_count\": 5\n}","name":null},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/wordcount/","auth":"required","examples":{"codes":[{"code":"#!/bin/bash\ncurl -v -H \"Authorization: ApiKey $UNBABEL_USERNAME:$UNBABEL_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -X POST https://api.unbabel.com/tapi/v2/wordcount/ \\\n        -d '{\n                \"text\": \"Text to be translated\"\n            }'","language":"shell"}]},"method":"post"},"editedParams2":true,"isReference":false,"slug":"post-wordcount","childrenPages":[]}

post/wordcount/

Count words on a text

Body Params

text:
required
string
From where we will be counting all the words

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format