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

<script>
var myAwesomeVar = 'This is a text I would like to translate';
</script>

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

<div data-slide-title="Title slide">
    New project !
</div>

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

<?php

add_filter( 'weglot_get_dom_checkers', 'custom_weglot_dom_check' );
function custom_weglot_dom_check( $dom_checkers  ) { //$dom_checkers contains the list of all the class we are checking by default

	class Div_Slide_Title extends Weglot\Parser\Check\Dom\AbstractDomChecker {
		const DOM       = 'div'; //Type of tag you want to detect // CSS Selector
		const PROPERTY  = 'data-slide-title'; //Name of the attribute in that tag uou want to detect
		const WORD_TYPE = Weglot\Client\Api\Enum\WordType::TEXT; //Do not change unless it's not text but a media URL like a .pdf file for example.
	}
	$dom_checkers[] = '\Div_Slide_Title'; //You add your class to the list because you want the parser to also detect it
	return $dom_checkers ;
}

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).

\Weglot\Parser\Check\Regex\RegexChecker( $regex = '' , $type = '' , $var_number = 0 , $keys = array() );

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

<script type="text/javascript">
    jQuery(document).ready(function ($) {

        // Untranslate text
        alert("My untranslate text");
        console.log("My untranslate text", "My untranslate text");

        // Untranslate HTML
        $("body").append("<p>My <strong>untranslate</strong> text</p>");

        // Untranslate JSON values
        var myJson = {
            "MyKey1": {
                "MyKey1-1": "My untranslate text",
                "MyKey1-2": "My untranslate text"
            },
            "MyKey2": "My untranslate text",
            "some_array" : [ "Hello" , "Translate this"]
        };

    });
</script>
<script type="text/template">"\r\n\t\t\t<div class=\"sticky-sidebar\">\r\n\t\t\t\t\ ....  \t\t<\/div>\r\n\r\n\t\t\t"</script>
<div data-escapedjson="{&quot;schema&quot;:{&quot;content&quot;:{&quot;desktop&quot;:&quot;&lt;h1&gt;Translate it&lt;\/h1&gt;&quot;}}}"><h1>This, no problem</h1></div>

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.

<?php

add_filter( 'weglot_get_regex_checkers', 'custom_weglot_add_regex_checkers' );

function custom_weglot_add_regex_checkers( $regex_checkers ) {

    // Text
    $regex_checkers[] = new \Weglot\Parser\Check\Regex\RegexChecker( '#alert\(\"(.*)\"\);#', 'TEXT', 1 );
    $regex_checkers[] = new \Weglot\Parser\Check\Regex\RegexChecker( '#console\.log\(\"(.*?)\",.*?\"(.*?)\"\);#', 'TEXT', 2 );

    // HTML
    $regex_checkers[] = new \Weglot\Parser\Check\Regex\RegexChecker( '#\$\(\"body\"\)\.append\(\"(.*)\"\);#', 'HTML', 1 );

    // JSON
    $regex_checkers[] = new \Weglot\Parser\Check\Regex\RegexChecker( '#var myJson = ((.|\s)+?);#', 'JSON', 1, array('MyKey1-1', 'MyKey1-2', 'MyKey2' , 'some_array') );
    
    //More advanced : HTML after a callback
    $regex_checkers[] = new \Weglot\Parser\Check\Regex\RegexChecker( "#<script type=\"text\/template\">(.*)<\/script>#", "HTML", 1, array(),"json_decode" , "json_encode");
    
    //More advanced : JSON after a callback
    $regex_checkers[] = new \Weglot\Parser\Check\Regex\RegexChecker( '#data-escapedjson="((.|\s)+?)"#', 'JSON', 1, array(), "html_entity_decode" , "htmlentities" );
    
    //More advanced : JSON after a callback, version with another regex
    $regex_checkers[] = new \Weglot\Parser\Check\Regex\RegexChecker( '#data-escapedjson="(.*)"#', 'JSON', 1, array(), "html_entity_decode" , "htmlentities" );
    
    return $regex_checkers;
}

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:

{
    "name":"My name value, already translated", //Will be translated by default because key is "name"
    "description":"My description value, already translated", //Will be translated by default because key is "description"
    "my_custom_key":"<p>HTML content, already translated</p>", //Will be translated by default because we detect this is HTML
    "message":"My message value to translate!" //This will not be translated and you will need to use the filter
}

To do this, we use weglot_add_json_keys filter.

<?php

add_filter( 'weglot_add_json_keys',  'custom_weglot_add_json_keys' );
function custom_weglot_add_json_keys(  $keys  ){ //$keys already contains "name" and "description"
    $keys[]  =  'message'; //This tells Weglot to also look for key "message" when detecting content to translated
    return $keys;
}

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

{
    "url" : "https://mysite.com/contact",
    "redirectURL" : "https://mysite.com/contact",
    "niceURL" : "https://mysite.com/contact",
    "name" : "This is my name"
}

The translated response would be

{
    "url" : "https://mysite.com/fr/contact",
    "redirectURL" : "https://mysite.com/fr/contact",
    "niceURL" : "https://mysite.com/contact",
    "name" : "C'est mon nom"
}

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

<?php

add_filter( 'weglot_words_translate', 'custom_weglot_words_translate' );
function custom_weglot_words_translate( $words ){        
    $words[] = "Monday";       
    $words[] = "Tuesday";    
    $words[] = "Nice to meet you";           
    return $words;
}

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.

<?php

add_filter( 'weglot_html_treat_page', 'custom_weglot_html_treat_page_1' );
function custom_weglot_html_treat_page_1( $html ) {

    $s = 'https://codex.wordpress.org/';
    $r = 'https://codex.wordpress.org/fr:Accueil';

    $html = str_replace( $s, $r, $html );
    return $html;
}

Use case 2

In this example, the replacement occurs according to the chosen language.

<?php

add_filter( 'weglot_html_treat_page', 'custom_weglot_html_treat_page_2' );
function custom_weglot_html_treat_page_2( $html ) {

    $search = 'https://codex.wordpress.org/';

    switch ( weglot_get_current_language() ) {
        case 'fr':
            $html = str_replace( $search, 'https://codex.wordpress.org/fr:Accueil', $html );
            break;
        case 'pt':
            $html = str_replace( $search, 'https://codex.wordpress.org/pt:Página_Inicial', $html );
            break;
    }

    return $html;
}

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.