Angsuman’s Translator Plugin Pro / Gold: Application Program Interface

Overview

Angsuman’s Translator Plugin Pro comes with extensive array of options accessible from the plugin management console. We also provide additional customizability and access to the inner data structures through simple php based API (Application Program Interface). This allows you to fine-tune your display.

Note: Use the tags / functions in your template files (of your theme) only.

The functionalities can be grouped into the following sections:

Flag Display

ATPP 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 14 languages are available for English (base language) in the Pro version and 33 languages are available, for English, in the Gold version. 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 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 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 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 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>";
}
}
?>


Content Display

Translator Plugin Pro & Gold 5.0 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 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-->

Skipping data consumes no resource.

Translator plugin also comes with editor button to skip translating text in post or pages. In wordpress 2.1 and later versions skip translation button doesn’t show in post editor in WYSIYG mode but it works fine in text mode. So wordpress 2.1 and later version users are requested to edit / write post in text mode or add skip translation tags manually as shown above.

Statistics

Translator Plugin Pro 5.0 provides detailed statistics on the plugin usage as well as the effectiveness of the intelligent caching engine.

The statistics is available from Translator Plugin Pro Options panel in Basic tab and in Advanced -> Cache Management tab.

You can also display summary statistics for your blog users using the Translator Stats widget, available from Presentation -> Sidebar Widgets menu when a widget enabled theme is used (like Anaconda) along with the widget plugin.

Note: The widget plugin is not required for WordPress 2.2 or later as it is part of the core.

The summary statistics for display on your web pages are available through a custom tag / API as described below:
<?php if(function_exists('tgGetTranslatorStats')) echo tgGetTranslatorStats() ?>