ICanLocalize can be used as a translation server for any application.
- 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.
See below the steps to setup a project and send contents to translation. If you prefer a hands on approach, download the
ICanLocalize API sample code (PHP)
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:
|User email (all communication will be done with that email address)|
|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||Description 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 (1 – notify the user when translations are complete)|
|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.
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’.
Updating website configuration
If you need to update the language pairs, the pickup mode or any other settings, you can use the update method:
|id||The cms id, obtained when creating the account|
|accesskey||An access key, also obtained after account creation|
The other arguments are the same as for account creation.
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_languageN arguments. For example, if you want to translate from English to Spanish and French, you should specify:
- from_language1 = English
- to_language1 = Spanish
- from_language2 = English
- to_language2 = French
Step 2) Sending HTML documents to translation
|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)|
|permlink||Document’s URI (optional)|
|file1[uploaded_data]||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.
The document content should be encoded in base64 and embedded into the following XML structure:
<?xml version="1.0" encoding="utf-8"?> <cms_request_details type="sitepress" command="translate_content" from_lang="English"> <link url="http://www.iclapiuser.com?page_id=12"/> <contents> <content type="title" translate="1" data="SUNhbkxvY2FsaXpl" format="base64"/> <content type="body" translate="1" data="VHJhbnNsYXRpb24gU2VydmljZQ==" format="base64"/> </contents> <cms_target_languages> <target_language lang="Portuguese"/> </cms_target_languages> </cms_request_details>
The link is the URI of the document sent to translation.
The content type is used to identify each content entry and can be any string (not only title or body).
Currently, only one target language per request is accepted.
Step 3) Returning translations
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 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.
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:
ICanLocalize will send you the translated file as response.
This file will be a gziped XML similar to the one you sent, but containing the translations nested to each content item:
<cms_request_details command="translate_content" from_lang="English" type="sitepress"> <link url="http://www.ipin.com" /> <contents> <content data="SUNhbkxvY2FsaXpl" format="base64" translate="1" type="title"> <translations> <translation data="SUNhbkxvY2FsaXpl" lang="Portuguese"/> </translations> </content> <content data="VHJhbnNsYXRpb24gU2VydmljZQ==" format="base64" translate="1" type="body"> <translations> <translation data="U2VydmnDp28gZGUgVHJhZHXDp8Ojbwo=" lang="Portuguese"/> </translations> </content> </contents> <cms_target_languages> <target_language lang="Portuguese"/> </cms_target_languages> </cms_request_details>
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.
- status: 3