Translate services

Navigate CMS has a special kind of extension to allow translating content. In particular, this kind of extensions populate the Translate button found below the tinyMCE editors when editing elements.

To illustrate how to write a translate service extension we'll expain the Google Translate plugin.

Plugin definition

{
    "title": "Google Translate",
    "version": "1.0",
    "author": "Naviwebs",
    "website": "http://www.naviwebs.com",
    "description": "Translate texts using the paid Google Translate service",
    "type": "translate",
    "options": [
        {
            "id": "google_translate_api_key",
            "name": "Google Translate API Key",
            "type": "value"
        }
    ],
    "bindings": [
        {
            "module": "elements",
            "event": "edit",
            "function": "nvweb_google_translate_initialize_javascript"
        },
        {
            "module": "webdictionary",
            "event": "edit",
            "function": "nvweb_google_translate_initialize_javascript"
        }
    ]
}

As you probably know, Google Translate is a paid service. When you subscribe to it Google gives you an API Key. You need to send the API key in every translation request. For this reason, the extension needs to know that value and that's why an extension configuration option is there.

The second thing you should notice is "type": "translate". Navigate CMS recognizes the translate service extensions by searching that string. Your service will not be included in the dropdown button unless you set the value "translate" to the property "type".

Finally, all translation service extensions must implement some special javascript functions and must be loaded before any request. Right now (as of Navigate CMS 1.7), only two functions are enabled to send translation requests: webdictionary and elements. The bindings section of the definition forces the initialization of the required translation functions when a webdictionary or element item is in edit mode.

In other words, when the user wants to edit a content or webdictionary text, a the PHP function "nvweb_google_translate_initialize_javascript" is called. That function is located in the main executable PHP file of the extension: google_translate.php. Let's take a look:

function nvweb_google_translate_initialize_javascript()
{
    global $layout;

    $extension = new Extension();
    $extension->load('google_translate');

    $layout->add_script("

        $.getScript('plugins/google_translate/js/jquery.translate.min.js', function()
        {
            $.translate.load('".$extension->settings['google_translate_api_key']."');
        });

        function navigate_tinymce_translate_google_translate(element, to, from)
        {
            //...
        }

        function navigate_textarea_translate_google_translate(element, to, from)
        {
            //...
        }

        function navigate_translate_google_translate(element, to, from)
        {
            //...
        }
    ");
}

Our Google translate extension uses the famous jQuery translate plugin to send the translation requests. This jQuery plugin needs to be loaded before doing requests, so the initialization function is the perfect place to do it. We also pass the API Key of the extension configuration found by loading the extension as an object.

Next is write the three required special functions:

• navigate_tinymce_translate
• navigate_textarea_translate
• navigate_translate

These functions must have the extension name at the end; in our example the extension is called "google_translate":

• navigate_tinymce_translate_google_translate
• navigate_textarea_translate_google_translate
• navigate_translate_google_translate

All functions receive the same three parameters:

• element — DOM object that wants its contents translated
• original language — source language, may be empty if can't be determined
• destination language

Except on a few cases, the original language can't be detected in Navigate CMS so you need to use an external service to get that information. Fortunately, Google translate doesn't need the source language as itself has a very good detection algorithm.

Let's see the simplest of the three functions:

function navigate_translate_google_translate(element, language_to, language_from)
{
    $.translate( 
        $(element).val(), 
        language_to,
        {   
            data: false,
            toggle: false,
            async: false,
            complete: function(translation)
            {
                $(element).val(translation);
            }
        }
    );
}

This first function is just a wrapper to a jQuery translate call. We just read the value of the source element and request the translation. Once received we replace the source element value.

function navigate_textarea_translate_google_translate(element, to, from)
{
    var bdfrom = $(element).val();

    var tmp_translate = $('<div id="navigate_jquery_translation">'+bdfrom+'</div>');

    $("body").append(tmp_translate);

    $("#navigate_jquery_translation").translate(
    {  
        from: "",
        to: translate_to,
        replace: true,
        async: false,
        complete: function()
        {
           bdfrom = $("#navigate_jquery_translation").html();
           $(element).val(bdfrom);
           $("#navigate_jquery_translation").remove();
        }
    });
}

This function is used to retrieve and translate the text of textarea elements. It's slightly more complicated but has the same principle as the first function: a wrapper to the jQuery translate plugin.

Finally we have the function to translate HTML code from a tinyMCE control:

function navigate_tinymce_translate_google_translate(element, to, from)
{
    var bdfrom = tinyMCE.get(element).getContent({ format: 'raw' });

    var tmp_translate = $('<div id="navigate_jquery_translation">'+bdfrom+'</div>');

    $("body").append(tmp_translate);

    $("#navigate_jquery_translation").translate(
    {  
        from: "",
        to: translate_to,
        replace: true,
        async: false,
        complete: function()
        {
            bdfrom = $("#navigate_jquery_translation").html();
            tinyMCE.get(element).setContent(bdfrom, { format: 'raw' });
            $("#navigate_jquery_translation").remove();
        }
    });
}

As we see, the main difference between the three functions is the way of getting and setting the original / translated text.

With all these instructions you should be able to create a translate extension for Navigate CMS. The quickest way is take the Google translate extension and modify the code to suit your translation service.

0 Comments