Skip to content
Treehill Studio

System Settings

BabelTranslate contains some system settings in the babeltranslate namespace.

These are available in the MODX system settings panel.

Key Name Description Default
babeltranslate.debug Debug Log debug information in the MODX error log. No
babeltranslate.deepl_auth_key DeepL API Auth Key The DeepL auth key to access the DeepL API. -
babeltranslate.deepl_text_translation_options DeepL Text Translation Options [Since 1.2.3] JSON-encoded object of DeepL text translation options. The options can be found in the DeepL API Docs. @FILE or @CHUNK bindings can be used. -
babeltranslate.openai_api_url OpenAI API Url [Since 1.5.0] The OpenAI compatible service URL -
babeltranslate.openai_auth_key OpenAI API Auth Key [Since 1.5.0] The OpenAI auth key to access to the OpenAI API. -
babeltranslate.openai_metadata OpenAI Chat Metadata [Since 1.5.0] JSON-encoded object of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format and for querying objects via the API or the Dashboard. -
babeltranslate.openai_model OpenAI Model [Since 1.5.0] The model ID used to generate the response, such as gpt-4o or o1. OpenAI offers a wide range of models with different capabilities, performance characteristics and price points. -
babeltranslate.openai_store Store Response [Since 1.7.0] Store the generated model response for later retrieval via API. Has also be enabled in OpenAI. No
babeltranslate.openai_temperature Temperature [Since 1.5.0] The sampling temperature to use (between 0 and 1). Higher values such as 0.8 will make the output more random, while lower values such as 0.2 will make it more focused and deterministic. -
babeltranslate.openai_text_translation_options Text translation instructions [Since 1.5.0] Instructions to the model on how to approach the translation task. Could be used to give instructions on formality, tone of voice or specific vocabulary to use. @FILE or @CHUNK bindings can be used. -
babeltranslate.reverso_api_url Reverso API Url [Since 1.3.0] The API url for accessing the Reverso API -
babeltranslate.reverso_password Reverso Password [Since 1.3.0] The password to access the Reverso API. -
babeltranslate.reverso_text_translation_options Reverso Text Translation Options [Since 1.3.0] JSON-encoded object of Reverso text translation options. @FILE or @CHUNK bindings can be used. -
babeltranslate.reverso_username Reverso Username [Since 1.3.0] The Reverso username to access the Reverso API. -
babeltranslate.timelimit Time Limit [Since 1.7.0] The number of seconds a translation may take. On shared hosts, the value can usually be no more than 30 seconds. 30
babeltranslate.translate_duplicate Translate Babel Duplicate Translate the duplicate Babel resource directly. No
babeltranslate.translate_resource_cb_fields Translate ContentBlocks Fields JSON-encoded object of ContentBlocks fields that need to be translated. Each record contains the ContentBlocks field ID as a key, the value contains several options: type is optional (it is otherwise set by the ContentBlocks field type) and can be filled with text, single, grid or repeater. nested is optional (it is otherwise set by the ContentBlocks field type) and it can contain the key of the nested values in the ContentBlocks value. fields is optional (it defaults to ["value"]) and it can be filled with an array of field names which will be translated. @FILE or @CHUNK bindings can be used. -
babeltranslate.translate_resource_cb_layouts Translate ContentBlocks Layout Settings [Since 1.6.0] JSON-encoded object of ContentBlocks layout settings that need to be translated. Each record contains the ContentBlocks layout ID as a key, the value currently contains one option: settings contains an array of settings keys where the value is translated. @FILE or @CHUNK bindings can be used. -
babeltranslate.translate_resource_fields Translate Fields Comma-separated list of resource fields that need to be translated. @FILE or @CHUNK bindings can be used. pagetitle, longtitle, content, alias
babeltranslate.translate_resource_tvs Translate Template Variables JSON-encoded object of template variables that need to be translated. Each record contains the template variable name as a key, the value contains several options: type is optional (it is otherwise set by the template variable type) and can be filled with text, single, grid or custom. fields is optional (it defaults to ["value"]) and it can be filled with an array of field names which will be translated. @FILE or @CHUNK bindings can be used. -
babeltranslate.translator Translator service The main translator service. Defaults to the first available translator service in the babeltranslate.translators system setting. deepl
babeltranslate.translators Translator services [Since 1.3.1] Comma-separated list of translator services (deepl, reverso and openai are currently possible). The first available translator service for each language is used. deepl

Examples for the babeltranslate.translate_resource_cb_fields and babeltranslate.translate_resource_tvs settings can be found on the examples page.

The settings babeltranslate.translate_resource_fields, babeltranslate.translate_resource_tvs and babeltranslate.translate_resource_cb_fields can use @FILE or @CHUNK bindings. Path placeholders like {core_path}, {base_path} and {assets_path} can be used. All paths have to stay inside the MODX base path because of security reasons.

Setup OpenAI

The following steps have to be done to use OpenAI as translator:

  1. Create an account at https://platform.openai.com.
  2. Setup billing at https://platform.openai.com/settings/organization/billing/overview.
  3. Create an API key with all permissions at https://platform.openai.com/settings/organization/api-keys.
  4. Copy the API key and make sure you save it somewhere. You will only be able to copy it once.
  5. In MODX, go to system settings and filter the namespace with: babeltranslate.
  6. Set the babeltranslate.openai_auth_key system setting to the API key you just copied.
  7. Optionally change the babeltranslate.openai_api_url system setting. It defaults to https://api.openai.com/v1/.
  8. Optionally change the babeltranslate.openai_model system setting. It defaults to gpt-4.1-mini.
  9. Optionally change the babeltranslate.temperature system setting. It defaults to 0.2.
  10. Optionally change the babeltranslate.metadata system setting. It defaults to {}.
  11. Optionally change the babeltranslate.store system setting. It defaults to false.
  12. Optionally change the babeltranslate.text_translation_options system setting. It defaults to an empty value.

Custom template variable translation type

The custom type of babeltranslate.translate_resource_tvs will be handled by a plugin in OnBabelTranslateCustomTV. There exist a disabled skeleton plugin in the BabelTranslate category. Duplicate and edit that plugin to add your own translation handling.

The plugin can use the following event properties:

Property Content
translator The translator class. Translating a string is done by $translator->translate($string, $fromCulture, $toCulture).
resource The current translated resource.
tvname The name of the translated template variable.
value The value of the translated template variable.
fromCulture The culture the value is translated from.
toCulture The culture the value is translated to.