UsageLast updated: 15 October 2022
Translations are created by adding one or more {exp:jcogs_mts:translate} or {exp:jcogs_mts:translate_all} tags to your document.
Note: To avoid complications arising from inadvertent translations of mark-up content, EE Auto-Translate does not attempt to translate any of:
- The HTML
<head>section of a web page - The content of any HTML
<script>or<style>tags - The content of any EE comments within the template
- The content of any late-parsed EE short-form tags (i.e.
pathandtemplatevariables)
Auto-Translate will remove these sections from any translation text regardless of the setting chosen for Ignore HTML tags either as a default setting or if specified in a tag as a parameter.
Due to limitations of the HTML processing routines employed by machine translation services some HTML processing errors might still arise from translations, especially when using translate_all tags. If this happens let JCOGS Design know: fixes to some issues may be possible.
Note: Not all languages are available as either target or source languages - the limitations are determined by each machine translation service provider. If you attempt to translate to or from a language that is not supported by the machine translation service provider you are using, EE Auto-Translate will report an error. To assist you in ensuring that you specify valid languages, the {exp:jcogs_mts:languages} tag is provided - see its support text for details.
Single Tag
The text to be translated is included as the variable text= within a single {exp:jcogs_mts:translate} tag.
The tag must contain a to= parameter to specify the required target language for the translation using the appropriate two-letter ISO 639-1 country code.
Additional parameters can be added to the tag to let you over-ride any default parameter values.
On processing the tag is replaced with the translated text.
Illustration
Translate some text to German (source language determined automatically)
Tag Used
{exp:jcogs_mts:translate to="DE" text={source}}
Source
My cat is a black domestic short-hair called 'Killer'.
Result
Meine Katze ist eine schwarze Hauskatze, kurzhaarig.
Pair Tag
The text to be translated is wrapped between an opening / closing pair of {exp:jcogs_mts:translate} tags.
The opening must contain a to= parameter to specify the target language for the tranlsation, along with any optional parameters chosen.
The language to translate to is specified using the appropriate two-letter ISO 639-1 country code. Additional parameters added to the tag let you over-ride any default parameter values.
On processing the text enclosed by the tag-pair is replaced with the translated text.
Illustration
Translate to German using a tag-pair (source language determined automatically)
Tag Used
{exp:jcogs_mts:translate to="DE" }{source}{/exp:jcogs_mts:translate}
Source
My cat is a black domestic short-hair called 'Killer'.
Result
Meine Katze ist eine schwarze Hauskatze, kurzhaarig.
Translate All Tag
In the special case that you want to translate all of the output of a template, you can add the {exp:jcogs_mts:translate_all} tag to your template.
The tag must contain a to= parameter to specify the required target language for the translation using the appropriate two-letter ISO 639-1 country code.
Additional parameters can be added to the tag to let you over-ride any default parameter values.
On processing the text enclosed by the tag-pair is replaced with the translated text.
Illustration
Use the translate_all tag to translate into German (source language determined automatically)
Tag Used
{exp:jcogs_mts:translate_all to="DE"}
Source
My cat is a black domestic short-hair called 'Killer'.
Result
Meine Katze ist eine schwarze Hauskatze, kurzhaarig.
Usage Notes
If you put a translate_all tag into a template, any and all translate tags will be ignored: this is to avoid translation of the same text multiple times within the same template parse.
Usage Notes
Should you put more than one {exp:jcogs_mts:translate_all} tag in a template, the one nearest to the end of the template when parsing occurs (i.e. after expansion of all EE content tags) will be the one used.
What languages are available?
Machine translations can only be made to languages supported by the machine translation service provider you are using. The Languages tag-pair provides access to this list of available langauges. The available list is returned via three 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
Illustration
Tag Used
{exp:jcogs_mts:languages service="deepl"}{iso_code}{name}{if supports_formality}Y{/if}{/exp:jcogs_mts:languages}
Result
| ISO Code | Language | Supports Formality? |
|---|---|---|
| BG | Bulgarian | |
| CS | Czech | |
| DA | Danish | |
| DE | German | Y |
| EL | Greek | |
| EN-GB | English (British) | |
| EN-US | English (American) | |
| ES | Spanish | Y |
| ET | Estonian | |
| FI | Finnish | |
| FR | French | Y |
| HU | Hungarian | |
| ID | Indonesian | |
| IT | Italian | Y |
| JA | Japanese | Y |
| KO | Korean | |
| LT | Lithuanian | |
| LV | Latvian | |
| NB | Norwegian | |
| NL | Dutch | Y |
| PL | Polish | Y |
| PT-BR | Portuguese (Brazilian) | Y |
| PT-PT | Portuguese (European) | Y |
| RO | Romanian | |
| RU | Russian | Y |
| SK | Slovak | |
| SL | Slovenian | |
| SV | Swedish | |
| TR | Turkish | |
| UK | Ukrainian | |
| ZH | Chinese (simplified) |
Usage Notes
Some providers also limit translations to text provided in one of an approved list of source languages; the Languages tag can provide this list also. Which list you get is determined by the direction= parameter.
Setting the Target Language
A key requirement for the Auto-Translation tag to work is the specification of the target language for the translation.
Auto-Translate provides three different mechanisms for setting the target language to be used within a translate tag.
- You can set the target language explicitly using the to= parameter within the translate tag (using a value which in turn you may set by referring to a dyanmic elements such as a URL slug or a value written to a data variable within the template HTML etc.)
- e.g.
{exp:jcogs_mts:translate to="{segment_1}"}
- e.g.
- You can request the target language to be set according to the value of a nominated GET variable - for example the value from a
<select>element within a form on the calling page- e.g.
{exp:jcogs_mts:translate use_get_variable_for_target="language_code"}
- e.g.
- You can set the target language to use the target language previously saved into a session variable
- e.g.
{exp:jcogs_mts:translate use_saved_language="y"}
- e.g.
If you specify more than one target language choice within the same tag, the value set for to= dominates, followed by the saved language code, followed by the value set from a GET variable.
Service usage data
Machine translation services offer some free translations (typically 500,000 characters) and thereafter charge per character translated within a billing period. The {exp:jcogs_mts:usage} tag-pair provides you information about the current status of your use of a service within the current billing period. The available list is returned via two 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.
Illustration
Tag Used
{exp:jcogs_mts:usage service="deepl"}
Monthly character usage: {character_count} out of {character_limit}
{/exp:jcogs_mts:usage}
Source
Result
Monthly character usage: 0 out of 500000