Documentation - Auto-Translate

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.

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 = no default value.

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 currently available is below some 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.

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. Default = deepl.

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

save_target_language

Saves a nominated language to a php session variable.

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 session variable used is set to expire after 300 seconds if the session variable is not accessed within that time by Auto-Translate. Each time Auto-Translate accesses the variable it resets the count-down timer - so this session variable will be deleted 300 seconds after the final transaction that involves retrieving the saved language value.

If this tag is called and the browser is set to reject php session variables then no value will be saved.
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.

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 retrieving the current saved target language using the use_saved_language= parameter
set by reference to a GET variable - simply specify the name of the variable to look for. The variable is typically set through an HTML <form> element - for example from a <select> form element.

Parameters

cache= time in seconds to cache translation results. Default set in Control Panel settings.
from= 2-letter ISO code of language to translate from (default=auto).
service= short name of service provider. Current options deepl. Default = deepl.
text= for single-tag use defines text to be translated.
to= 2-letter ISO code of language to translate to [required].
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= parameter.
use_get_variable_for_target= set this to y to specify a GET variable name to use to determine the target language to use. Ignored if either to= or use_saved_language= parameters are set.
xml= Whether to ignore <xml> tags. Options yes|no. Default set in Control Panel settings.

Usage Notes

Caching
If the output of a translate tag is cached the cache copy is accessed using a hash of the text provided in the original translation operation. So to be sure that a cached copy of a translation is used, it is important to ensure that the text to be translated remains the same. If the text contains elements that change between uses (e.g. output of the current time) then this will cause the text-block to be translated to not be the same as previously, and so the cached copy will not be used. To avoid this, use multiple translate tags in series each containing part of the text to translate with the aim of isolating the 'changing' text within one or more separate translate tag(s) - the non-changing tags will be cached OK, and the amount of text translated each time the template is parsed can then be minimised.

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 template variable content in the translated output (as these are parsed by EE after translation is completed).

translate_all

Specifies that whole of output of current template should 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 retrieving the current saved target language using the use_saved_language= parameter
set by reference to a GET variable - simply specify the name of the variable to look for. The variable is typically set through an HTML <form> element - for example from a <select> form element.

Parameters

cache= time in seconds to cache translation results. Default set in Control Panel settings.
from= 2-letter ISO code of language to translate from (default=auto).
service= short name of service provider. Current options deepl. Default = deepl.
to= 2-letter ISO code of language to translate to [required].
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= parameter.
use_get_variable_for_target= set this to y to specify a GET variable name to use to determine the target language to use. Ignored if either to= or use_saved_language= parameters are set.
xml= Whether to ignore <xml> tags. Options yes|no. Default set in Control Panel settings.

Usage Notes

Caching
If the output of a translate tag is cached the cache copy is accessed using a hash of the text provided in the original translation operation. So to be sure that a cached copy of a translation is used, it is important to ensure that the text to be translated remains the same. If the text contains elements that change between uses (e.g. output of the current time) then this will cause the text-block to be translated to not be the same as previously, and so the cached copy will not be used.

Usage Notes

Multiple tags in a single template
You can add as many tags to a template as you wish, but only the one that appears closest to the end of the template output when parsing is complete will be acted upon.

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 template variable content in the translated output (as these are parsed after translation is completed).

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.