Home » Programming Interface

Programming Interface

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.

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:

POST: https://www.icanlocalize.com/websites/create_by_cms.xml

Arguments:

Argument Description
email 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 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.

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’.

Updating website configuration

If you need to update the language pairs, the pickup mode or any other settings, you can use the update method:

POST: https://www.icanlocalize.com/websites/update_by_cms.xml

Arguments:

Argument Description
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.

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_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

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
permlink Document’s URI (optional)
file1[description] “cms_request_details”
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

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.

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.

Call:

POST: https://www.icanlocalize.com/websites/wID/cms_requests/CMS_REQUEST_ID/update_status.xml?language=DESTINATION_LANG_NAME

Arguments:

  • status: 3