Please enter a search term to begin your search.

Translator Plugin Gold Developer Guide

Translator Plugin Gold provides an extensive Open API to customize all aspects of the display, target or exclude content specifically from original or translated pages and more.

Content Display

Translator Plugin Gold allows you to create blocks of content which are visible only on translated pages. For example you may want to notify your readers that the translated versions of the page are machine generated and hence may not be equivalent to human translation. Now you can easily do so with the custom tags / api provided.

Translator Plugin Gold also allows you to create / specify blocks of content which are available only in the original language. For example you may want to make your comment section available only in the English version of the blog. Now you can easily do it with a simple tag / api as explained below.

How to display content only on translated pages

You can use the tags / code shown below to display content which is visible only in translated pages.

<?php if(function_exists('tgInTranslatedPage') && (tgInTranslatedPage())) { ?>
    The HTML Content here will only be visible on translated pages.
<?php } ?>

How to exclude content from translated pages

To exclude content from translated pages use the tags as shown below:

<?php if(function_exists('tgInTranslatedPage') && (!tgInTranslatedPage())) { ?>
    The HTML Content here will not be visible in translated pages.
<?php } ?>

Note: For php developers, the function tgInTranslatedPage() returns true only in translated pages.

How to skip translating certain content

You can use the skip-translation tags as shown below to skip translating certain content from translated pages.

<!--skip translation-->
Content you do not want to translate
<!--end skip translation-->

Translator Bar Display

Translator Plugin Gold provides four display format to display the hyperlinked flag icons which are used to translate a page. For example the flags in Simple Thoughts blog are displayed with CSS styling on None format. However we have also opened up the functionality with the API to allow you to fully customize the flags, associated hyperlinks, text messages??? in short everything. You may not even display the flags, just provide hyperlinked text for each language.

tgGetAvailableLanguages()

tgGetAvailableLanguages returns an array containing all the available languages. The available languages is limited by the languages supported in your license (pro or gold) for your base language (language the blog is written in). Currently Translator Plugin Gold supports 41 languages, for base language English. The languages are represented by short codes like ???de??? or ???es???. This is not necessarily the number of visible languages or languages which are currently enabled for translation. Refer to tgGetVisibleLanguages() to get an array of all visible languages. The other functions, which requires a language parameter, depends on this function to validate their argument against the set of available languages.

tgGetVisibleLanguages()

tgGetVisibleLanguages returns an array containing all the languages which are currently enabled for translation on your blog. This is a subset of tgGetAvailableLanguages(). You can limit the number of languages you want to provide translation by unchecking all the languages you want to exclude in Translator Plugin Gold engine configuration located in Advanced->Language & Engine Configuration section. tgGetVisibleLanguages() returns the languages which are used internally to display the translator flags in the display formats we provide. You should use this with functions like tgGetFlagImage(), tgGetTooltip(), tgGetTranslatedPageURL().

tgGetFlagImage($language)

This returns the flag image url for any available language. The available language *must* be one of the languages returned by tgGetAvailableLanguages().

For example tgGetFlagImage('de') will return the url for German flag. To echo it you can use:

<?php if(function_exists('tgGetFlagImage')) echo tgGetFlagImage('de'); ?>

tgGetTranslatedPageURL($language)

This identifies the current page and returns the url for translated version of the page. This function is not associated in any way with ???the WordPress loop???. You can place it anywhere within the page like sidebar or header or footer etc.

The specified language *must* be one of the languages returned by tgGetAvailableLanguages().

For example tgGetTranslatedPageURL('de') will return the url for German version of the current page. To echo it you can use:

<?php if(function_exists('tgGetTranslatedPageURL')) echo tgGetTranslatedPageURL('de'); ?>

tgGetBaseLanguage()

This returns the code for the base language the blog is written in. For example for an english blog the base language returned will be en.

The following code will echo the base language of your blog:

<?php if(function_exists('tgGetBaseLanguage')) echo tgGetBaseLanguage(); } ?>

tgGetTooltip($language)

This returns the tooltip text for any available language. The tooltip text contains the translated version of ???Translate to $language??? along with an English text of the language. This is used to create the tooltip over the flags in display.

The available language *must* be one of the languages returned by tgGetAvailableLanguages().

Let???s wrap it up with an example. The following code will display a translator bar with all the available languages in free format. This is a simplified version of the None display format without the CSS adornments.

<?php 
if(function_exists('tgGetVisibleLanguages')) { // This ensures that the Translator Plugin Gold is active.
    $visibleLanguages = tgGetVisibleLanguages();
    foreach($visibleLanguages as $language) {
        echo "<a href='" . tgGetTranslatedPageURL($language) . "' title='" . tgGetTooltip($language) . "'><img style='border:0;' src='" . tgGetFlagImage($language). "' alt='" . tgGetTooltip($language) . "' /></a>";
    }
}
?>

Translator Post Filter Hook

Translator Plugin Gold provides a new hook / callback facility which allows you to view and process the translated page before it is served to the end user. You can use the tgTranslatorPostFilterHook to edit / modify the content of the translated pages before it is served to the user as described below

You can also take action based on the content or engine used to translate the page.

This hook can be used to handle errors in translation or even catch and process new types of errors. The actions include 1. ability to send custom error pages, 2. re-direct to original pages (for example in case of error), 3. displaying custom error messages and more. Few use cases for this hook are:

  • Provide customized title, meta tags & descriptions for translated pages to eliminate concerns about duplicate content. Check out the translated pages in simple thoughts for some usage examples (hint: look at the meta tags and title).
  • Provide custom error pages or re-direct to original page when translator is unable to translate a page (due to overload or temporary unavailability of engines).
  • Filter translated pages
  • Add your own content to translated pages like advertisements etc. You can also do it using existing translator API. However this provides full control over processing translated pages before it is served to the end-user.

function tgTranslatorPostFilterHook($data, $language, $engine, $url, $translationError) {

    if(!$translationError) {
        // post-process your translated page content. $data contains translated page content.
    }
    return $data;

}

Note: For any translation error $translationError will be set to true.

Translator Pre Filter Hook

Translator Plugin Gold, with its latest release of Translator Pluging Gold 2.1, provides a new hook/ callback facility which allows you to take a decision before the translation process begins.

  • Manage the translation for a set of translation languages. For example you can cancel the translation for Hindi language.
  • Manage the translation for a category of pages. For example you can stop the translation for archive pages.
  • Provide custom error pages or re-direct to original page for selected pages / languages affront without hitting the translation engines and it will reduce the translation cost.
  • Modify translated page content, provide customized title, meta tags & descriptions for translated pages to eliminate concerns about duplicate content when the translated page content served from translator cache.
  • Manage translation rate which prevents you from temporary or permanent banning by translation engines.
  • You can also change charset before serving the translated page content from translator cache.

tgTranslatorPreFilterHook can identify the three specific events:

  1. Whether the translated page content is served from translator cache
  2. Whether it is a new translation request i.e. the translated page data is not served from translator cache
  3. Whether it is a background translation refresh request

It takes an array as argument. For the three above events the data structure of this array are different as described below:

Translated pages served from translator Cache

Array
(
'url' => Translation url,
'language' => Translation language,
'data' => Translated Data,
'inCache' => 1))
)

Note:  'data' contains translated page content from cache
       inCache' is set to 1 when the translated page content served from translator cache

New Translation Request (Translated page content not in translator cache)

Array
(
'url' => Translation url,
'language' => Translation language,
)
Note: Use this for a new translation request that is not in cache.

Background Cached Translator Page refresh request

Array
(
'url' => Translation url,
'language' => Translation language,
'refreshCache' => 1));
)
Note:refreshCache' is set to 1 when it is an background translation refresh request

function translatorPreFilter($val) {
    if(isset($val['inCache']) && $val['inCache'] && isset($val['data'])) {
        // pre process cached translated page content here. $val['data'] contains translated page content.
    } else if(isset($val['refreshCache']) && $val['refreshCache']) {
        // Background refresh request
    } else {
        // New translation request
    }
    return $val;
}

How to change charset before serving the translated page content from cache

function translatorPreFilter($val) {
    if(isset($val['inCache']) && $val['inCache'] && isset($val['data'])) {
        @header('Content-Type: text/html; charset=UTF-8'); // sets charset to UTF-8
    }
    return $val;
}