`

JCOGS Auto-Translate

Multiple vendors now provide machine translations via API services - including Google and DeepL.

EE-AutoTranslate provides a simple tag-based method for accessing such translation services via:

  • a unified control panel to store api keys, account status information and access to add-on documentation;
  • if a service allows for it, an option to determine whether <html> tags are included in the translation;
  • an option to allow translated text to be cached;
  • an option to add useful debug information to the EE template profile log;
  • [in version 2] provide a mechanism to fail-over between enabled service providers (e.g. when 'free' translation limits are reached on a provider, or a source / target language not supported by chosen service).

N.B. Currently EE-AutoTranslate V1 supports only the DeepL machine translation service. Future versions will add support for similar services from other providers, for example Google and Microsoft.

Installation

Copy the jcogs_mts folder to your system/user/addons folder and then install from the ExpressionEngine Control Panel Add-ons page.

Configuration

Configuration of the add-on is required before it can be used.

Configuration is controlled using the add-on settings page which can be accessed from the ExpressionEngine Control Panel Add-ons page.

API keys

Machine translation services require an API key to authorise the translation transactions.
EE Auto-Translate will not work without at least one valid API key being added to the settings page.

Enable translation?

This slider controls whether a machine translation service is to be used. If a service is disabled in this settings panel, any EE Auto-Translate tags that are configured to use the service will have no function regardless of any parameters they may contain. Upon processing the EE Auto-Translate tags will simply return the specified text unchanged to the template.

Ignore XML tags by default?

Some machine translation services provide the option to exclude <XML> tags from the translation being carried out - which in practice allows for <html> mark-up to be ignored; the text returned from a translation run retains whatever <html> tags it included unchanged.

This setting determines the default option for {exp:jcogs_mts:translate} and  {exp:jcogs_mts:translate_all} tags.

Regardless of the default setting <html> processing can be determined on a per-tag basis by adding the xml= parameter to a tag.

Caching: Default time period (s) to keep a cached copy of translations

Machine Translation Services charge per character translated. To minimise use EE Auto-Translate attempts to cache all translation results. This configuration setting allows you to specify the default period that a translation will be kept alive in the cache. Setting this value to 0 will effectively disable caching by default.

The default cache value can always be overridden by use of the cache= parameter.

Caching is carried out using the EE Caching Service: if the EE Cache Manager is used to clear All Caches the translation cache will also be cleared.

Debugging: Enable debug messages?

If this option is enabled then EE Auto-Translate will write additional messages to the Templates tab within the EE Page Debug report.

Usage

Translations are created by adding one or more {exp:jcogs_mts:translate} or {exp:jcogs_mts:translate_all} tags to your document.

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.

    {exp:jcogs_mts:translate 
        value="My cat is a black domestic short-hair called 'Killer'." 
        to="DE"
    }
    -> "Meine Katze ist eine schwarze Hauskatze, kurzhaarig, namens 'Killer'."

Tag Pair

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.

    {exp:jcogs_mts:translate 
        to="DE"
    }
    My cat is a black domestic short-hair called 'Killer'.
    {/exp:jcogs_mts:translate}
    -> "Meine Katze ist eine schwarze Hauskatze, kurzhaarig, namens 'Killer'."

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.

    {exp:jcogs_mts:translate_all 
        translate-to="DE"
    }
    My cat is a black domestic short-hair called 'Killer'.
    -> "Meine Katze ist eine schwarze Hauskatze, kurzhaarig, namens 'Killer'."

Notes

Note 1

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.

Note 2

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.

Note 3

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. path and template variables)

Despite this, due to limitations of the XML processing routines employed by the machine translation services some HTML processing errors might arise from translations, especially when using translate_all tags. If this happens let JCOGS Design know: fixes to some issues may be possible.

Note 4

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.

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
    {exp:jcogs_mts:languages service="deepl"}
        {iso_code}{name}{if supports_formality}Y{/if}
    {/exp:jcogs_mts:languages}
    ->
    ISO Code     Name         Supports Formality?
    bg            bulgarian    
    cs            czech    
    da            danish    
    de            german        Y
    ... etc ...

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.

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.
    {exp:jcogs_mts:usage service="deepl"}
    Monthly character usage: {character_count} out of {character_limit}
    {/exp:jcogs_mts:usage}
    ->
    "Monthly character usage: 14147 out of 500000"

Tag Reference

{exp:jcogs_mts:languages}

Description

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

{exp:jcogs_mts:translate}

Description

Specifies text to be translated.

Parameters

  • cache= time in seconds to cache translation results. Default set in Control Panel settings.
  • service= short name of service provider. Current options deepl. Default = deepl.
  • text= for single-tag use defines text to be translated.
  • from= 2-letter ISO code of language to translate from (default=auto).
  • to= 2-letter ISO code of language to translate to [required].
  • 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.
  • 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.
  • 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.
  • 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).

{exp:jcogs_mts:translate_all}

Description

Specifies that whole of output of current template should be translated.

Parameters

  • cache= time in seconds to cache translation results. Default set in Control Panel settings.
  • service= short name of service provider. Current options deepl. Default = deepl.
  • from= 2-letter ISO code of language to translate from (default=auto).
  • to= 2-letter ISO code of language to translate to [required].
  • 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.
  • 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.
  • 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.
  • 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).

{exp:jcogs_mts:usage}

Description

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.

Support

Support is available from JCOGS Design via email sent to mts_addon@jcogs.net or via @JCOGS Design the EE Slack discussion area.

Changelog

1.0.1 (22 July 2021)
  • Clean up distribution files
1.0.2 (22 July 2021)
  • Correct some typos
  • Enable debug control in CP settings area
1.0.3 (24 July 2021)
  • Move utility functions to Services
  • Improve registration of extension hooks
1.0.4 (30 September 2021)
  • Now works with EE5!
  • Correct typos in documentation
1.0.7 (20 October 2021)
  • MSM Support