Skip to content



The translation library provides the possibility to automatically translate content. This is realized via the implementation of an API.

Please refer to the admin documentation on to get an explanation of all the config parameters that are available in the instance configuration.


The main way to enable the translation of content is to use the <xui:translation> tag. The content inside this tag will be sent to the translation module and (if not set otherwise) translated into the language of the current viewing user.

// Example usage of xui:translation in a .tpl file


    <xui:param name="document_index_id">
        <xt:echo marker="" />
    <xui:param name="cache_key">content</xui:param>
    <xt:echo marker="model.content_html" escape="false"/>


The following parameters can be used inside the translation tag:

document_index_id [int]: Links the translation to a document index id

cache_key [string]: only relevant in combination with document_index_id. Defines a second identification method for content inside a model (e.g: $model->title and $model->content). If a document_index_id is set, but no cache_key, the cache_key '_default' is used.

target_language [string]: Only use if you want to request a special language. If blank, the current set language setting of the user is used.

translation_only [0|1]: If active only the translated content (or the original content, if no translation is available yet) is displayed without any indication that it is translated text. default: 0

minimal [0|1]: If minimal is set, the translation will only be indicated by the icon_globe symbol. If this option is not set, the displayed content will contain the original content and the translated content. default: 0

minimal_switch [0|1]: only relevant in combination with minimal. If set, a click on the icon_globe symbol will toggle between the original and the translated content. default: 1

Automated Translation Process

The automated translation process currently includes the translation of the xui tags and the the translation of the search index if enabled (see instance config options).

The translation module will first look into its database tables to check if the requested content already has a translated version available. If not it will create a translation_job element with a translation request for the API in the desired language. If set in the instance config (Translate on demand only) it will create translation jobs for all system languages which have no translation yet.

No new translation_job will be created, if there is already an open job for the exact same content and target_language in the database.

The daemon of the translation module will process these jobs and send requests to the configured api. The translation result is stored in the corresponding object, referenced by id in the translation_job entry.

If there is an error returned from the api, the error_cnt of the translation_job is increased by one and the reason for the error is logged into XF->lib->error. Jobs with a higher error count than 4 will no longer be fetched from the Database and will not be processed. There is currently no mechanism to automatically delete these entries.

If the process detects a change in content, it will delete the translation model and will create a new translation_job for the required language(s).

Translation Models

There are currently two types of models which store the translations.

  • TranslationDocument: for elements with an entry in the document index. (forum posts, wiki articles, etc.) These elements are identified by the document_index_id and the cache_key

  • Translation: for elements without an entry in the document index. (messenger messages, etc.) These elements are identified by its content hash. Currently there is no mechanism in place to automatically delete no longer relevant entries.

Runtime translations

It is possible to request translation during runtime by using the method getTranslated of the TranslationController. This is the same method, the automatic inline translation calls, to get either an already cached translation back, or to create a new translation_job if there is no translated_content for the requested language. If the method argument $force_translation is set to true, the created translation_job will not be saved, but processed immediately. This is a synchronous process and make take some time, but the translation for the required language will be available as return value.

Translation statistics

The table translation_counter stores all translation calls that are made. The statistic includes the call count, word count and character count on a daily per language basis,

## Translation-Feedback / -Correction / -Improvement ## It is possible to improve a automated translation. In places where a non minimal inline translation is shown (with both, original and translated content), there will be a link reachable through the dropdown menu in the folded content display, where it is possible to call the translation_feedback page (Check the access rights in the instance config). Inputs done on this page will be stored in the translation_feedback table. If this user improvement is present, inline translations will display this user improved content instead of the automated content. The short profile of the user who did the improvement will also displayed. There is only one improvement possible for each translation model. If the translation is improved again by the same or a different user, the originally stored improvement will be overwritten.

If the API offers a possibility (e.g.: Transperfect) to feed these improvements back into its learning mechanism a feedback_job is created which will be processes by the daemon. If there are feedback_jobs available, they will be processed after the translation_jobs in the daemon process() method.