UsageLast updated: 13 August 2024
Translations are created by adding one or more {exp:jcogs_mts:translate} or {exp:jcogs_mts:translate_all} tags to your template.
- JCOGS Auto-Translate will attempt to translate any text that appears between an opening and closing {exp:jcogs_mts:translate} tag.
- JCOGS Auto-Translate will attempt to translate all the text that appears in the template output of any template that includes an {exp:jcogs_mts:translate_all} tag.
What does not get translated … ?
To avoid complications arising from inadvertent translations of content, EE Auto-Translate does not attempt to translate any of:
- The content 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) - Due to limitations in the EE template parser, JCOGS Auto-Translate is not able to translate the content of any Single Global Variables.
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. See the tag reference section for more information.
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
[[trans_tag_6862107b9d6bec536a76252668593d8cca83ee3c{"to":"de","from":"","html":"html","which_service":"deepl","cache_time":"316224000","get_post_variable":"","use_saved_language":"n"}]]
My cat is a black domestic short-hair called[[/trans_tag_6862107b9d6bec536a76252668593d8cca83ee3c]]
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. See the tag reference section for more information.
The language to translate to is specified using the appropriate two-letter ISO 639-1 country code.
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
[[trans_tag_f8b07a5aa6e43923b9557e663ce2c99d63110cf0{"to":"de","from":"","html":"html","which_service":"deepl","cache_time":"316224000","get_post_variable":"","use_saved_language":"n"}]]
My cat is a black domestic short-hair called[[/trans_tag_f8b07a5aa6e43923b9557e663ce2c99d63110cf0]]
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. See the tag reference section for more information.
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
[[trans_tag_6862107b9d6bec536a76252668593d8cca83ee3c{"to":"de","from":"","html":"html","which_service":"deepl","cache_time":"316224000","get_post_variable":"","use_saved_language":"n"}]]
My cat is a black domestic short-hair called[[/trans_tag_6862107b9d6bec536a76252668593d8cca83ee3c]]
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 two variables:
{iso_code}- the two-letter ISO code for the country / language{name}- the name of the language
The DeepL machine translation service also supports language formality rules for some languages. If you request the languages listing while using the DeepL service, an additional value will be returned for each language relating to DeepL's transaltion capabilities for each language with regard to formality.
{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? |
|---|---|---|
| ar | Arabic | |
| bg | Bulgarian | |
| zh-hans | Chinese (simplified) | |
| zh-hant | Chinese (traditional) | |
| cs | Czech | |
| da | Danish | |
| nl | Dutch | Y |
| en-us | English (American) | |
| en-gb | English (British) | |
| et | Estonian | |
| fi | Finnish | |
| fr | French | Y |
| de | German | Y |
| el | Greek | |
| hu | Hungarian | |
| id | Indonesian | |
| it | Italian | Y |
| ja | Japanese | Y |
| ko | Korean | |
| lv | Latvian | |
| lt | Lithuanian | |
| nb | Norwegian | |
| pl | Polish | Y |
| pt-br | Portuguese (Brazilian) | Y |
| pt-pt | Portuguese (European) | Y |
| ro | Romanian | |
| ru | Russian | Y |
| sk | Slovak | |
| sl | Slovenian | |
| es | Spanish | Y |
| sv | Swedish | |
| tr | Turkish | |
| uk | Ukrainian |
Usage Notes
DeepL also limits 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. See the tag reference section for more information.
Setting the Target Language
Auto-Translation requires the specification of a 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 dynamic 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 use these options to specify more than one target language choice within the same tag, JCOGS Auto-Translate will preferentially use the value set for to= , followed by the value set from a GET variable, followed by the saved language code.
Service usage data
Several machine translation services offer some free translations (typically 500,000 characters per month) and thereafter charge per character translated within a billing period.
The DeepL service makes this usage information available through its API, and so for this service 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.
Unfortunately at this time the MS Azure AI Translator does not provide any information about translation usage during the current billing period through its API. If you are using the MS Azure AI Translator service, the {exp:jcogs_mts:usage} tag is ignored.
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: 138 out of 500000