Translations Hooks
WordPress Filters relating to detecting & translating words
Weglot plugin will detect all the words in your HTML. To do this, it will parse the DOM in PHP and detect the inner text of HTML nodes but also some attributes we have defined, like the "placeholder" attribute in a <input>
node or the "alt" attribute of an img
node.
This usually ensure all the text in your page is detected and get translated. However, in some case, your text can be located in other location in your HTML. Like it could be in a JavaScript variable like this
In that case, your text will not be detected and not be translated.
This is where you will use filters to extend the definitions of the Weglot Parser and instruct it to detect other text
weglot_get_dom_checkers
This filter extend the list of HTML nodes and attribute that are being translated.
Argument | Type | Description |
$dom_checkers | String | Names of used DomChecker (extends Weglot\Parser\Check\Dom\AbstractDomChecker) |
Use case
It can happen in your HTML that you use data-attributes that are not translated by default. Example with data-slide-title
With this the weglot_get_dom_checkers
filter, you will extend the list of "Dom checkers" by adding a class in the list like on the following example. Y
weglot_get_regex_checkers
This filter is a bit more tricky to understand but also very powerful. It allows you to give a Regex to the parser in order for it to detect the text you want in your DOM.
Argument | Type | Description |
$regex_checkers | array | Used RegexChecker |
$regex_checkers is an array that contains the RegexChecker objects, which determine what elements to treat as well as the type of data it is (TEXT, HTML or JSON).
The RegexChecker constructor settings are as follows:
$regex: Regex that target the element you want to be parsed
$type: String variable that determines the type of the targeted element ('TEXT', 'HTML' or 'JSON')
$var_number: Denotes the number of variable targeted by the regex that you want to parse
$key: If the element being treated is a ‘JSON’ element, this variable allows you to specify keys to translate
$decode_function: Function callback applied to intercepted content
$encode_function: Function callback applied to returned content
Use case
Below are several examples of content that will not be translated by default by Weglot, but that you can translate using this filter
In order for the content in this example to be interpreted, and then translated, we will use the weglot_get_regex_checkers filter as followed.
weglot_add_json_keys
Weglot also translates JSON response but not all values. Use this filter to target specific values.
Argument | Type | Description |
$keys | array | Array of string |
The JSON values translated by default are:
Value with key: "name"
Value with key: "description"
Value in HTML format
Use case
You may come across values used in your JSON that are not translated by default.Here’s an example using the message value:
To do this, we use weglot_add_json_keys filter.
Also, note that if a URL is detected in a value of the JSON, it will be replaced by the URL with the language code if and only if it is one of the redirecturl
, url
, link
. For example, if you original JSON is
The translated response would be
Adding keys to check when replacing URL will be done weglot_ajax_replace_urls
weglot_words_translate
Use this filter to target a specific word literally in your source code
Argument | Type | Description |
$words | array | Array of string |
You can add words that are present in your HTML page but not translated. It's useful when a word is not being translated by Weglot because it's inside a JavaScript for example and you can't really use other filters.
Use case
This filter will tell Weglot to look literally for words in your source code, then translate it and literally replace these words in your source code. Be very careful to not enter keywords as "head" "body" for example as it could break your page.
weglot_html_treat_page
Use this filter when there is no other solution : It's a very powerful filter that allows you to make manual edition on the final translated DOM in PHP.
Argument | Type | Description |
$html | string | HTML content of translated page |
Use case 1
The following code replaces all of the “https://codex.wordpress.org/” links with “https://codex.wordpress.org/fr:Accueil” in the translated versions.
Use case 2
In this example, the replacement occurs according to the chosen language.
Note, you can use weglot_render_dom
instead, which is the same except there is the HTML of the button and the links are already translated.
Dynamic Selectors
1. Enabling Dynamic Content Translation
To enable the use of dynamic content translation on your website, add the following filter:
This filter allows Weglot to handle the translation of dynamic content, which may change after the initial page load (e.g., content updated via JavaScript).
Defining Custom Selectors
Next, define the selectors that Weglot should use to identify dynamic content. We achieve this by creating a custom function:
The function
custom_weglot_dynamics_selectors()
returns an array of CSS selectors. These selectors specify which parts of your website's content should be treated as dynamic.For example,
.wp-block-woocommerce-cart
and.wp-block-woocommerce-checkout
target WooCommerce cart and checkout blocks.
3. Applying Custom Selectors to Weglot Filters
To use the custom selectors defined above, apply them to both the dynamic and whitelist selector filters:
weglot_dynamics_selectors
: This filter allows Weglot to recognize dynamic content based on the selectors you defined.weglot_whitelist_selectors
: This filter specifies elements that Weglot should always translate, ensuring that the specified content is included in translations.
By using the same function for both filters, you can reuse the list of selectors for both dynamic and whitelisted content.
Specifying URLs for Applying Custom Translations
Lastly, define where your custom dynamic translations should be applied. By default, this is set to an empty value, but you can configure it to apply to all URLs or a specific list:
weglot_allowed_urls
: This filter determines on which URLs the custom translation rules will be applied.Setting the value to
'all'
ensures that your custom selectors will work on every page of your website. You can also pass an array of specific URLs if you only want the rules to apply to certain pages.
- External JavaScript Dependency for Custom Code
When using the dynamic code, it requires an external JavaScript script to be loaded correctly for it to function as expected.
Key Considerations:
Script Loading: If the external script fails to load or is not included properly on the page, the custom code will not work. Make sure that the script is loaded before the code is executed.
defer
Attribute Issues: If the external script is loaded with thedefer
attribute, it may cause unexpected behavior or delays, especially if your custom code depends on the script being fully available before execution.Solution: To ensure that your custom code works seamlessly, you may need to exclude this specific script from being deferred. This way, the script will load immediately and be available when your code is executed, avoiding potential timing issues.
How to Exclude the Script from
defer
Check how your scripts are being loaded (especially if you’re using a plugin or optimization tool that automatically adds the
defer
attribute).Ensure the script tag for your external JavaScript looks like this:
By excluding the
defer
attribute, the script will be executed as soon as it is downloaded, ensuring your custom code runs without issues.
Last updated