ICanLocalize can be used as a translation server for any application.
Key features
- Professional translation
- All translations are done by professional translators, writing in their native languages. ICanLocalize hires the translators and validates their translation qualifications. Clients can choose the translators who work on their projects from the translators in ICanLocalize’s pool.
- Self service
- Clients set up their projects, choose translators and send contents to translation. There’s no need to a project manager, so projects can run quickly and on a low budget.
- Fully embedded solution
- All interaction between clients and translators can be embedded in the host application. Clients don’t need to visit ICanLocalize site.
How it works
Generally, there are two types of calls:
- Calls to ICanLocalize server – done using HTTP / HTTPS using XML data structures.
- Notification from ICanLocalize server to the host server. These are done using XML-RPC.
Step 1) Set up a project
All translations are grouped into projects. A project can include several translation languages, each assigned to a translator.
To create a project, call:
POST: https://www.icanlocalize.com/websites/create_by_cms.xml
Arguments:
| Argument | Description |
|---|---|
| User email (all communication will be done with that email address) | |
| fname | First name |
| lname | Last name |
| password | Password (optional) |
| create_account | 0 – use and existing account (password required), 1 – create a new account (password will be emailed) |
| is_verified | Set to 1 |
| platform_kind | Set to 2 |
| interview_translators | Set to 1 |
| cms_kind | Each type of CMS gets a unique identifier. Contact ICanLocalize. |
| cms_description | Name of the content management system |
| url | URL of website (include http://) |
| title | Title of website |
| description | Desciption of website |
| pickup_type | 0 – ICanLocalize will send XML-RPC notifications / 1 – host system will poll translations |
| notifications | Integer value, determining which notifications to send |
| project_kind | 0 – test, 2 – production |
| from_languageN | Name of destination language N (projects can have any number of language pairs) |
| to_languageN | Name of target language N (each destination language needs to have a corresponding target language) |
On success, ICanLocalize will return an XML structure with the project information.
ICanLocalize Accounts
Each project belongs to an ICanLocalize account. When you create a project, you can either create a new ICanLocalize account or use an existing one.
If you’re creating an account, you need to specify the fname, lname and email fields. The server will generate a password and send it to your email.
If you already have an ICanLocalize account, you should include the email and password fields. The server will check that they are correct and create the new project in that account.
Translation Pickup Options
The pickup_type argument determines how translations are returned to your site.
When set to XML-RPC (0), ICanLocalize will send you an XML-RPC notification about completed translations. Then, your server will call ICanLocalize, fetch the completed translations and mark them as ‘delivered’. This option is recommended if your server is online, accessible through the web and can handle XML-RPC notifications.
When set to polling (1), ICanLocalize will not send any notifications when translations complete. You should set a cron job that regularly checks for completed translations. When your server sees that there are completed translations, it should fetch them and mark them as ‘delivered’.
Language Names
All language names, in this and other calls, are the English names. You can use the supported translation languages as reference.
To specify the translation languages, use pairs of from_languageN and to_langaugeN arguments. For example, if you want to translate from English to Spanish and French, you should specify:
- from_language1 = English
- to_langauge1 = Spanish
- from_language2 = English
- to_language2 = French
Step 2 (HTML): Sending HTML documents to translation
POST: https://www.icanlocalize.com/websites/wID/cms_requests.xml
Arguments:
| Argument | Description |
|---|---|
| orig_language | Name of original language |
| to_language1 | Name of the destination language |
| key | Unique identifier by CMS, per request, to protect against duplicate requests for the same contents |
| cms_id | Unique identifier by CMS, per source document, which links together document updates |
| title | Title of document |
| note | Note to translators (optional) |
| doc_count | 1 |
| file1 | The gzip compressed file for translation |
On successful request creation, ICanLocalize will return the request ID.
Key and cms_id
There are two unique identifiers which are not the same.
The key argument should protects against communication errors. It should be a unique string for creation / update of a translation.
The cms_id argument is unique to the source document in the CMS. For example, if you’re translating a page, who’s ID is 41, you can set it to ‘page_41′. The cms_id value allows ICanLocalize to link between different versions of the same document and provide incremental translation. When the same document updates, you should send it again to translation, using the same call. By keeping the same cms_id value as before, you tell ICanLocalize that this is the same document. Our system will translate only new or modified sentences (but return the entire translated document, using the translation memory).
Content for translation
The file1 argument is an attachment. You should use multitype encoding to send it. This should be a gzip encoded file that contains an XML with the content for translation.
Step 2 (text): Sending plain text for translation
Use the following call:
POST: https://www.icanlocalize.com/websites/wID/create_message.xml
Arguments:
| Argument | Description |
|---|---|
| body | Text to translate, base64 encoded |
| from_language | Name of source language |
| to_language | Name of destination language |
| signature | Integrity validation: MD5(body+from_languageto_language) |
On successful request creation, ICanLocalize will return the request ID.
Step 3) Returning translations
XML-RPC Notifications
When translation is complete, ICanLocalize will notify the host system. If the project is set to XML-RPC notifications, ICanLocalize will send the following XML-RPC:
icanlocalize.update_translation_status
ICanLocalize will send the document ID, language, translation status and signature.
Manually Polling for Completed Translations
When set to polling, ICanLocalize will not send any notification. In this case, your system should periodically call and check for completed translations.
Call:
GET: https://www.icanlocalize.com/websites/wID/cms_requests.xml?filter=pickup
You will get back an XML structure with the list of documents that are ready for pickup.
Fetching Completed Translations
When translations are complete, your system needs to fetch them and mark the as ‘delivered’.
You will have the cms_request_id of all completed jobs either from the XML-RPC notifications or from the polling call.
Then, per document, call:
GET: https://www.icanlocalize.com/websites/wID/cms_requests/CMS_REQUEST_ID/cms_download?language=DESTINATION_LANG_NAME
ICanLocalize will send you the translated file as response.
Marking Translations as Delivered
After your system fetches the completed translations, you should mark them as ‘delivered’. This tells ICanLocalize that you received the translation correctly.
Call:
POST: https://www.icanlocalize.com/websites/wID/cms_requests/CMS_REQUEST_ID/update_status.xml?language=DESTINATION_LANG_NAME
Arguments:
- status: 6