Obix Editor Xtd Translation Plugin

This system plugin allows translation of (selected) text from within a text editor.

Raison d'être

Just thought it might come in handy :)

Minimal requirements

Joomla! 5.0
PHP 8.2

Installation

The installation package contains a plugin and a library:

Editors Xtd - Obix Translator Plugin
Obix Translator Library

Installation of the package is the same as for any other Joomla! extension. If it is installed for the first time, as opposed to upgraded, the plugin should be activated automatically. Doesn't do any harm to check though :)

Description

The plugin is of the type Editor Xtd. Because operation of this group of plugins is triggered by a button below the editor area, they are often called Editor buttons. This plugin roughly provides the following functionality:

Translation of text that is marked for selection, replacing the marked text with the translated result.
Translation of text entered in a text area, inserting the result into the editor at the cursor position.

The actual translation is carried out by an external translation service. In its current incarnation the plugin (only) supports DeepL.

To make use of the service, the plugin must be able to access its API, for which it needs an authorisation code. That code can be obtained after creating a (free) account.

Available source and target languages for translation are directly dependent on the ones made available by the service.

Configuration

The plugin has several configuration settings that affect its behaviour:

DeepL autherisation code

The authentication code needed to access the DeepL API. Once you are logged into your service account, it can be obtained from your account page.

Selectable languages

Determines which languages are selectable when requesting a translation:

Available service languages: Allows choosing from any of the language offered by the service.
Installed site languages: Allows choosing from any of the languages installed on the site. This limits the length of the list of available languages, making it easier to choose from. ^*
Published site languages: Similar to the above, but only taking published languages into account.

Split sentences

Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects.

No splitting: No splitting at all, whole input is treated as one sentence.
On punctuation and on newlines: Splits on punctuation and on newlines.
On punctuation only: Splits on punctuation only, ignoring newlines.

Preserve formatting

Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects.

Formality

Default: No special treatment.
More formal: For a more formal language.
Less formal: For a more informal language.

Tag handling

Sets if HTML tags should be taken into consideration.

None: Tags will not be treated separately.
HTML: HTML tags will be mapped onto the appropriate location in the target text as good as possible.

Maximum retries

The maximum number of service requests, before the translation attempt is considered to have failed.

Timeout (sec.)

The time in seconds to wait for a service response, before a new request attempt is made.

Force TinyMCE button display

Forces display of the Translator button under the TinyMCE editor area when it is inadvertently hidden.

Caching

Determines if caching must be used to speed up retrieval of (relatively) static data, such as available service languges:

Global: Respect the global site setting.
Disable: Disable caching, irrespective of the global site setting.
Enable: Enable caching, irrespective of the global site setting.

Debug

When enabled, logs plugin specific debug information. For this to take effect, Debug System in the site's Global Configuration must be enabled as well.

^* Because Joomla! supports far more languages than DeepL, it is possible that the final list shows fewer languages than are installed on the site. The list can even be empty.

Usage

After the plugin is installed and properly configured, yet another editor button is displayed below the editor area:

Clicking the button, displays a modal popup window. The windows displays two select lists: one for selection of the source language and one for selection of the target language:

Translator popup

If no text was selected, the window displays an additional text area in which a source text ti be translated can be entered still:

Translator popup with teaxt area

An indication of the actual service quota, i.e. the character translation limit, the number of characters translated thus far and the number of remaining translatable characters, is displayed below the input fields. The free DeepL account allows translation of 500.000 characters per month.

Clicking the Translate button, invokes the translator service. The service then translates the source text, based on the selected languages. If - Try to detect - was selected for "Source language", the service will attempt to determine the source language from the source text. After the translated text is returned, it is pasted into the editor. If the original, untranslated source text originated from an editor selection, the selected text is replaced with the translated text. If the untranslated source text was entered in the text area of the popup window, the translated text is inserted in the editor at the cursor position.