Documentation - Auto-Translate

languages

The Languages tag-pair provides access to a list of available langauges for a particular service provider.

Parameters

direction= whether to get list for source or target languages. Current options from|to. Default = to.
service= short name of service provider. Current options deepl|microsoft. If the service provider to use is not specified, the default service choice is used.

Variables

{iso_code} - the two-letter ISO code for the country / language
{name} - the name of the language
{supports-formality} - a boolean value indicating whether translations for this language support defined levels of formality. Only provided if the selected service provider is DeepL.

translate

Specifies text to be translated.

The key parameter to set is the target language - which can be set in one of three ways:

set explicitly using the to= parameter
set by reference to a GET or POST variable - simply specify the name of a GET or POST variable to look for in the use_get_variable_for_target= parameter. The variable is typically set through an HTML <form> element - for example from a <select> form element.
set by retrieving the current saved target language previously saved via the save_target_language tag. Simply set the use_saved_language= parameter to ‘yes’.

Parameters

from= 2-letter ISO code of language to translate from. If left blank or set to auto the translation service being used will attempt to detect the source language from the text submitted. Specifying the source language can improve the speed and quality of translation results. (default=auto).
service= short name of service provider. Current options deepl|microsoft. Default = deepl.
text= for single-tag use, defines text to be translated.
to= 2-letter ISO code of language to translate to [required].
use_get_variable_for_target= set this to '<name of GET or POST variable>' to specify a GET or POST variable name to use to determine the target language to use. Ignored if theto=parameter is set.
use_saved_language= set this to y to use the currently saved language as the target language. Ignored if a value is set for to= or use_get_variable_for_target=parameters.

Usage Notes

Multiple tags in a single template
You can add as many tags to a template as you wish, provided you are mindful of the rules regarding nesting of tags. Each tag is evaluated separately, so you can include tags that translate to or from multiple languages within the same template.

Usage Notes

Nesting
Translate tags cannot be enclosed within other translate tag-pairs. Upon parsing, only the 'outer-most' tag pair found will be acted upon - any translate tags found within a tag pair will be ignored. This is to prevent multiple translations of the same text occuring within a single template parse. If a translate_all tag is found anywhere within the parsed template output, it always over-rides any translate tag - if you include a translate_all tag within parsed output any and all translate tags will be simply ignored during processing.

Usage Notes

Parse order Parsing of the translate tags is carried out very close to the end of the parse process. Due to limitations in the EE parse sequence, it is not currently possible to include global single variable content in the translated output (as these are parsed by EE after translation is completed).

translate_all

Specifies text to be translated.

The key parameter to set is the target language - which can be set in one of three ways:

set explicitly using the to= parameter
set by reference to a GET or POST variable - simply specify the name of a GET or POST variable to look for in the use_get_variable_for_target= parameter. The variable is typically set through an HTML <form> element - for example from a <select> form element.
set by retrieving the current saved target language previously saved via the save_target_language tag. Simply set the use_saved_language= parameter to ‘yes’.

Parameters

from= 2-letter ISO code of language to translate from. If left blank or set to auto the translation service being used will attempt to detect the source language from the text submitted. Specifying the source language can improve the speed and quality of translation results. (default=auto).
service= short name of service provider. Current options deepl|microsoft. Default = deepl.
to= 2-letter ISO code of language to translate to [required].
use_get_variable_for_target= set this to '<name of GET or POST variable>' to specify a GET or POST variable name to use to determine the target language to use. Ignored if theto=parameter is set.
use_saved_language= set this to y to use the currently saved language as the target language. Ignored if a value is set for to= or use_get_variable_for_target=parameters.

Usage Notes

Nesting
If a translate_all tag is found anywhere within the parsed template output, it always over-rides any translate tag - if you include a translate_all tag within parsed output any and all translate tags will be simply ignored during processing.

Usage Notes

Parse order Parsing of the translate tags is carried out very close to the end of the parse process. Due to limitations in the EE parse sequence, it is not currently possible to include single global variable content in the translated output (as these are parsed after translation is completed).

get_browser_language

Returns the current language setting for the user's browser.

Language code returned is the value of the HTTP_ACCEPT_LANGUAGE header variable - which typically comprises the IETF language code for the working language being used by the user's browser.

If the server is unable to obtain the HTTP_ACCEPT_LANGUAGE header variable for some reason, the tag returns a null response.

Usage Notes

If you set the to= parameter to the value returned from the get_browser_language tag, provided the language is one supported by your chosen machine translation service, you can cause text to be translated into the visitors preferred language.

save_target_language

Saves a nominated language to the EE cache.

This facility allows you to change the language used in translations without needing to either write a URL slug or add a marker variable to the HTML to indicate the current working language.

The cache value is saved with a unique identifier for each user, so multiple users of your site can each view it concurrently using their preferred language.

The cache value is set to expire after 300 seconds. Each time Auto-Translate accesses the cached language value it resets the count-down timer - so cached language will be deleted 300 seconds after the final transaction that involves retrieving the saved language value.

If this tag is called with no language specified no action is carried out.

Parameters

to= the ISO language code to save.

Usage Notes

Extending a saved language session
As noted, each time you recall the saved language value Auto-Translate will reset the php session variable duration to 300 seconds.

If for some reason you want to explicitly extend the duration of session variable a call to {exp:jcogs_mts:get_saved_language} with no parameters will have this effect.

get_saved_language

Gets information about the currently saved language.

If called with no parameter, the tag simply extends the current saved language session duration.

Parameters

return= determines what information is returned. Options are name which returns the name of the language saved, and iso which returns the iso code of the language saved. Default =iso.

Usage Notes

Calling this tag when no language has been saved has no effect.

good_to_go

A simple utility that returns ‘true’ or ‘false’ depending on whether the character usage on the API key in use is valid, and if it is a DeepL API key, whether it is currently below some nominated threshold of its capacity.

The tag is useful for flow control within a template - for example you could use it to disable auto-translate tags if your usage is approaching your monthly limit.

For example, if the API key has a monthly allowance of 500,000 characters, and current usage in this billing period is 350,000 characters, usage will be 70% of the monthly total, in which case:

{exp:jcogs_mts:good_to_go} would return “true” - as current usage is below the default threshold of 80% of monthly capacity
{exp:jcogs_mts:good_to_go threshold='60'} would return false, as usage is above the nominated threshold percentage.

Parameters

threshold= the threshold to decide if we are ‘good to go’ - integer value in range 0 - 100. Default = 80.
service= short name of service provider. Current options deepl. Default = deepl.

Usage Notes

If you have defined multiple API keys, this tag makes its decision based on the cummulative character count and character limits of all the currently valid API Keys defined.

usage

The Usage tag-pair provides access to current status of an API account with a particular service provider.

Parameters

service= short name of service provider. Current options deepl. Default = deepl.

Variables

{character_count} - the number of characters translated with this service in the current billing period.
{character_limit} - the maximum number of characters that can translated in the current billing period.