Skip to content

Hooks

Jump to bottom
Julien MA Jacob edited this page Aug 28, 2026 · 5 revisions

This page documents all the actions and filters exposed by wpLingua that you can use in your theme or a custom plugin to customize the translation behavior.

All hooks are prefixed with wplng_.

Table of contents

Actions

URL & Slug Translation

Content Interception (output buffering)

Language Switcher

Languages & hreflang

Dictionary & Links/Medias

DOM Parsing Exclusions

JSON Parsing Rules

HTML Attributes Translation

Compatibility & Core

Actions

wplng_initialized

Type: Action

File: wplingua.php

Description: Fired at the very end of wplng_start(), once every wpLingua action, filter, shortcode and Gutenberg block has been registered, and only if none of wpLingua's incompatibility checks (multisite, PHP version, .htaccess, permalinks, plugin conflicts...) stopped the bootstrap. Use it when you need to run code that depends on wpLingua being fully loaded.

Declaration:

do_action( 'wplng_initialized' );

Usage example:

<?php

add_action( 'wplng_initialized', function () {
	// wpLingua is fully loaded and active here
	error_log( 'wpLingua has been initialized' );
} );

URL & Slug Translation

wplng_url_translate

Type: Filter

File: inc/url.php

Description: Applied to every URL translated by wpLingua (menus, links, hreflang tags, switcher links...). Runs after wplng_url_translate_no_filter() has computed the translated URL, so you can post-process the final result.

Declaration:

function wplng_url_translate( $url, $language_target_id = '' ) {
	return apply_filters(
		'wplng_url_translate',
		wplng_url_translate_no_filter(
			$url,
			$language_target_id
		)
	);
}

Usage example:

<?php

add_filter( 'wplng_url_translate', function ( $translated_url ) {
	// Force https on every translated URL
	return set_url_scheme( $translated_url, 'https' );
} );

Related: wplng_get_url_current_for_language( $language_id )

wplng_url_is_translatable

Type: Filter

File: inc/url.php

Description: Determines whether a given URL should be processed/translated by wpLingua (admin URLs, REST API, feeds, files, and user-excluded URLs are rejected by default). Return true/false to force a URL to be considered translatable or not.

Declaration:

function wplng_url_is_translatable( $url = '' ) {
	// ...
	return apply_filters(
		'wplng_url_is_translatable',
		wplng_url_is_translatable_no_filter( $url ),
		$url
	);
}

Usage example:

<?php

add_filter( 'wplng_url_is_translatable', function ( $is_translatable, $url ) {
	// Never translate URLs under /shop/
	if ( str_contains( $url, '/shop/' ) ) {
		return false;
	}
	return $is_translatable;
}, 10, 2 );

Related: wplng_url_is_translatable( $url )

wplng_url_exclude_regex

Type: Filter

File: inc/url.php

Description: Returns the list of regular expressions (built from the plugin's "Excluded URLs" setting) used to exclude URLs from translation. Each entry is a full #regex# pattern. Use this filter to add or remove exclusion patterns programmatically instead of (or in addition to) the option page.

Declaration:

function wplng_get_url_exclude_regex() {
	// ...
	$url_exclude = apply_filters(
		'wplng_url_exclude_regex',
		$url_exclude
	);

	$wplng_url_exclude_regex = $url_exclude;

	return $url_exclude;
}

Usage example:

<?php

add_filter( 'wplng_url_exclude_regex', function ( $url_exclude ) {
	$url_exclude[] = '#^/private/#';
	return $url_exclude;
} );

wplng_url_original

Type: Filter

File: inc/url.php

Description: Applied to the result of wplng_get_url_original(), which strips the language segment from a translated URL to recover the original (source language) URL.

Declaration:

function wplng_get_url_original( $url = '' ) {
	// ...
	$url = apply_filters(
		'wplng_url_original',
		$url
	);

	return $url;
}

Usage example:

<?php

add_filter( 'wplng_url_original', function ( $original_url ) {
	return remove_query_arg( 'utm_source', $original_url );
} );

Related: wplng_get_url_original()

wplng_url_is_sitemap_xml

Type: Filter

File: inc/url.php

Description: Determines whether a given URL points to an XML sitemap (sitemap.xml, sitemap_index.xml, posts-sitemap.xml...). This detection is used to decide whether wpLingua should inject <xhtml:link> hreflang alternates into the sitemap output.

Declaration:

function wplng_url_is_sitemap_xml( $url = '' ) {
	// ...
	return apply_filters( 'wplng_url_is_sitemap_xml', $is_sitemap, $url );
}

Usage example:

<?php

add_filter( 'wplng_url_is_sitemap_xml', function ( $is_sitemap, $url ) {
	// Also treat a custom sitemap endpoint as a sitemap
	if ( str_contains( $url, '/custom-sitemap/' ) ) {
		return true;
	}
	return $is_sitemap;
}, 10, 2 );

wplng_api_call_translate_context

Type: Filter

File: inc/util.php

Description: Filters the "context" value (the calling page URL) sent to the wpLingua translation API when requesting text translations. The API can use this context to improve translation quality.

Declaration:

function wplng_get_context() {
	$context = 'UNKNOW';
	// ...
	return apply_filters(
		'wplng_api_call_translate_context',
		$context
	);
}

Usage example:

<?php

add_filter( 'wplng_api_call_translate_context', function ( $context ) {
	// Always report the canonical front page as context
	return home_url( '/' );
} );

Content Interception (output buffering)

These four filters are applied inside inc/buffering.php, on every AJAX call, REST (/wp-json/) call and normal page render that wpLingua intercepts via output buffering.

wplng_intercepted_html

Type: Filter

File: inc/buffering.php

Description: Applied to the raw HTML output before wpLingua parses and translates it. Useful to alter the markup prior to translation (e.g. removing/adding markup that should or shouldn't be processed).

Declaration:

$content = apply_filters( 'wplng_intercepted_html', $content );
$content = wplng_translate_html( $content, $args );
$content = apply_filters( 'wplng_translated_html', $content );

Usage example:

<?php

add_filter( 'wplng_intercepted_html', function ( $content ) {
	$content .= '<!-- Debug: content intercepted before translation -->';
	return $content;
} );

Related: [Content by Language – Hook on Untranslated HTMLhttps://github.com/julien-jacob/wplingua/wiki/Content-by-Language)

wplng_translated_html

Type: Filter

File: inc/buffering.php

Description: Applied to the HTML output after wpLingua has translated it, right before it is sent to the browser. Useful for post-processing translated markup (custom string replacements per language, adding markers, etc.).

Declaration:

$content = apply_filters( 'wplng_translated_html', $content );

Usage example:

<?php

add_filter( 'wplng_translated_html', function ( $content ) {
	if ( 'fr' === wplng_get_language_current_id() ) {
		$content = str_replace( 'Hello', 'Bonjour', $content );
	}
	return $content;
} );

Related: Content by Language – Hook on Translated HTML

wplng_intercepted_json

Type: Filter

File: inc/buffering.php

Description: Applied to raw JSON output (AJAX/REST responses) before wpLingua translates it. Symmetrical to wplng_intercepted_html but for JSON responses.

Declaration:

$output_translated = apply_filters( 'wplng_intercepted_json', $output_translated );
$output_translated = wplng_translate_json( $output_translated );
$output_translated = apply_filters( 'wplng_translated_json', $output_translated );

Usage example:

<?php

add_filter( 'wplng_intercepted_json', function ( $json ) {
	// Inspect / log raw JSON before translation
	return $json;
} );

wplng_translated_json

Type: Filter

File: inc/buffering.php

Description: Applied to JSON output (AJAX/REST responses) after wpLingua has translated it.

Declaration:

$output_translated = apply_filters( 'wplng_translated_json', $output_translated );

Usage example:

<?php

add_filter( 'wplng_translated_json', function ( $json ) {
	$data = json_decode( $json, true );
	// alter $data...
	return wp_json_encode( $data );
} );

wplng_enable_in_progress_feature

Type: Filter

File: inc/buffering.php

Description: Controls whether the "Load in progress" feature is enabled for logged-in editors (a front-end indicator/loader shown while a page's translation is being generated). Defaults to the wplng_load_in_progress option value.

Declaration:

$load_in_progress_enabled = apply_filters(
	'wplng_enable_in_progress_feature',
	get_option( 'wplng_load_in_progress', false )
);

Usage example:

<?php

// Force-disable the "Load in progress" feature regardless of the setting
add_filter( 'wplng_enable_in_progress_feature', '__return_false' );

Language Switcher

wplng_switcher_insert

Type: Filter

File: inc/switcher.php

Description: Filters the switcher's "insert" position (e.g. bottom-center), as configured in the option page or defaulted to bottom-center when invalid.

Declaration:

function wplng_get_switcher_insert() {
	// ...
	$insert = apply_filters(
		'wplng_switcher_insert',
		$insert
	);

	return $insert;
}

Usage example:

<?php

add_filter( 'wplng_switcher_insert', function ( $insert ) {
	return 'top-right';
} );

wplng_switcher_theme

Type: Filter

File: inc/switcher.php

Description: Filters the switcher's theme (e.g. light-simple-smooth).

Declaration:

function wplng_get_switcher_theme() {
	// ...
	$theme = apply_filters(
		'wplng_switcher_theme',
		$theme
	);

	return $theme;
}

Usage example:

<?php

add_filter( 'wplng_switcher_theme', function ( $theme ) {
	return 'dark-simple-smooth';
} );

wplng_switcher_style

Type: Filter

File: inc/switcher.php

Description: Filters the switcher's display style (e.g. list, dropdown, block).

Declaration:

function wplng_get_switcher_style() {
	// ...
	$style = apply_filters(
		'wplng_switcher_style',
		$style
	);

	return $style;
}

Usage example:

<?php

add_filter( 'wplng_switcher_style', function ( $style ) {
	return 'dropdown';
} );

Related: Toggle dropdown language switcher by click

wplng_switcher_name_format

Type: Filter

File: inc/switcher.php

Description: Filters how language names are displayed in the switcher (e.g. original, id-based, or translated names).

Declaration:

function wplng_get_switcher_name_format() {
	// ...
	$name_format = apply_filters(
		'wplng_switcher_name_format',
		$name_format
	);

	return $name_format;
}

Usage example:

<?php

add_filter( 'wplng_switcher_name_format', function ( $name_format ) {
	return 'original';
} );

wplng_switcher_html

Type: Filter

File: inc/switcher.php

Description: Filters the final HTML markup of the language switcher, right before it's returned/echoed by wplng_get_switcher_html(). Also receives the website language data and the array of target languages, for full customization.

Declaration:

$html = apply_filters(
	'wplng_switcher_html',
	$html,
	$language_website,
	$languages_target
);

return $html;

Usage example:

<?php

add_filter( 'wplng_switcher_html', function ( $html, $language_website, $languages_target ) {
	// Wrap the switcher in a custom container
	return '<div class="my-switcher-wrapper">' . $html . '</div>';
}, 10, 3 );

Related: Toggle dropdown language switcher by click

Languages & hreflang

wplng_language_website_flag

Type: Filter

File: inc/languages.php

Description: Filters the flag image URL used for the website's original language, as returned by wplng_get_language_website_flag().

Declaration:

function wplng_get_language_website_flag() {
	// ...
	$website_flag = apply_filters( 'wplng_language_website_flag', $website_flag );

	return esc_url( $website_flag );
}

Usage example:

<?php

add_filter( 'wplng_language_website_flag', function ( $flag_url ) {
	return get_stylesheet_directory_uri() . '/images/custom-flag.svg';
} );

Related: wplng_get_language_website_id()

wplng_hreflang_x_default

Type: Filter

File: inc/hreflang.php

Description: Filters the URL used for the hreflang="x-default" <link> tag generated by wpLingua in the page <head>. Defaults to the English version's URL if available, otherwise the original URL.

Declaration:

$url_x_default = apply_filters( 'wplng_hreflang_x_default', $url_x_default );

if ( ! empty( $url_x_default ) ) {
	$html .= '<link';
	$html .= ' rel="alternate"';
	$html .= ' href="' . esc_url( $url_x_default ) . '"';
	$html .= ' hreflang="x-default"';
	$html .= '/>' . PHP_EOL;
}

Usage example:

<?php

add_filter( 'wplng_hreflang_x_default', function ( $url_x_default ) {
	return home_url( '/' );
} );

Dictionary & Links/Medias

wplng_dictionary_entries

Type: Filter

File: inc/dictionary.php

Description: Filters the final, sanitized list of dictionary entries (source term + per-language replacement rules) configured in the "Dictionary" option page, sorted by source string length. Use this to add or override dictionary entries programmatically.

Declaration:

$entries_clear = apply_filters(
	'wplng_dictionary_entries',
	$entries_clear
);

return $entries_clear;

Usage example:

<?php

add_filter( 'wplng_dictionary_entries', function ( $entries ) {
	$entries[] = array(
		'source' => 'wpLingua',
		'rules'  => array(
			'fr' => 'wpLingua', // Never translate the brand name
		),
	);
	return $entries;
} );

wplng_link_media_entries

Type: Filter

File: inc/link-media.php

Description: Filters the final, sanitized list of "Links / Medias" rules configured in the corresponding option page, sorted by source length. These rules let you rewrite specific links/media URLs per target language.

Declaration:

$entries_clear = apply_filters(
	'wplng_link_media_entries',
	$entries_clear
);

$wplng_link_media_entries = $entries_clear;

return $entries_clear;

Usage example:

<?php

add_filter( 'wplng_link_media_entries', function ( $entries ) {
	$entries[] = array(
		'source' => '/wp-content/uploads/logo.png',
		'mode'   => 'exactly',
		'rules'  => array(
			'fr' => '/wp-content/uploads/logo-fr.png',
		),
	);
	return $entries;
} );

DOM Parsing Exclusions

wplng_selector_exclude

Type: Filter

File: inc/dom/exclusion-put-tags.php

Description: Filters the full list of CSS selectors excluded from translation, made of wpLingua's built-in defaults, third-party plugin/theme compatibility selectors, and the user-defined "Excluded selectors" option, merged and deduplicated.

Declaration:

// Apply wplng_selector_exclude filters
$selector_exclude = (array) apply_filters(
	'wplng_selector_exclude',
	$selector_exclude
);

Usage example:

<?php

add_filter( 'wplng_selector_exclude', function ( $selectors ) {
	$selectors[] = '.my-custom-widget';
	return $selectors;
} );

wplng_excluded_editor_link

Type: Filter

File: data/node.php

Description: Filters the list of selectors for elements excluded from being made clickable/editable in wpLingua's visual editor overlay (textarea, pre, option by default).

Declaration:

$wplng_data_excluded_editor_link = apply_filters(
	'wplng_excluded_editor_link',
	array(
		'textarea',
		'pre',
		'option',
	)
);

Usage example:

<?php

add_filter( 'wplng_excluded_editor_link', function ( $selectors ) {
	$selectors[] = '.no-visual-edit';
	return $selectors;
} );

wplng_excluded_node_text

Type: Filter

File: data/node.php

Description: Filters the list of selectors whose text content (not their attributes) is excluded from translation (style, svg, canvas, link, script, code, .wpcf7-textarea by default).

Declaration:

$wplng_data_excluded_node_text = apply_filters(
	'wplng_excluded_node_text',
	array(
		'style',
		'svg',
		'canvas',
		'link',
		'script',
		'code',
		'.wpcf7-textarea',
	)
);

Usage example:

<?php

add_filter( 'wplng_excluded_node_text', function ( $selectors ) {
	$selectors[] = '.no-translate-text';
	return $selectors;
} );

wplng_excluded_ajax_action

Type: Filter

File: data/ajax.php

Description: Filters the list of action values (from $_POST['action']) that must be ignored by wpLingua's AJAX output-buffering interception (e.g. heartbeat, wpLingua's own internal AJAX actions).

Declaration:

function wplng_data_excluded_ajax_action() {
	return apply_filters(
		'wplng_excluded_ajax_action',
		array(
			'heartbeat',
			'wplng_ajax_heartbeat',
			'wplng_ajax_translation',
			'wplng_ajax_edit_modal',
			'wplng_ajax_save_modal',
			'wplng_ajax_slug',
			'wplng_load_in_progress',
		)
	);
}

Usage example:

<?php

add_filter( 'wplng_excluded_ajax_action', function ( $actions ) {
	$actions[] = 'my_plugin_internal_action';
	return $actions;
} );

JSON Parsing Rules

wplng_json_in_js_functions

Type: Filter

File: data/json.php

Description: Filters the whitelist of JavaScript function calls (dot notation) whose JSON argument should be parsed and translated by wpLingua (e.g. jQuery.datepicker.setDefaults).

Declaration:

$wplng_data_json_in_js_functions = apply_filters(
	'wplng_json_in_js_functions',
	array(
		'jQuery.datepicker.setDefaults',
		'$.datepicker.setDefaults',
	)
);

Usage example:

<?php

add_filter( 'wplng_json_in_js_functions', function ( $functions ) {
	$functions[] = 'MyPlugin.i18n.setDefaults';
	return $functions;
} );

wplng_json_rules_exclusion

Type: Filter

File: data/json.php

Description: Filters the list of callback rules used to decide whether a JSON element (identified by its value and its "path" of parent keys) must be excluded from translation. Each rule is a function( $element, $parents ) returning a boolean.

Declaration:

$wplng_data_json_rules_exclusion = apply_filters(
	'wplng_json_rules_exclusion',
	$logical_rules
);

return $wplng_data_json_rules_exclusion;

Usage example:

<?php

add_filter( 'wplng_json_rules_exclusion', function ( $rules ) {
	$rules[] = function ( $element, $parents ) {
		// Exclude any value nested under myPluginSettings.apiKey
		return $parents === array( 'myPluginSettings', 'apiKey' );
	};
	return $rules;
} );

wplng_json_rules_inclusion

Type: Filter

File: data/json.php

Description: Filters the list of callback rules used to force-include a JSON element for translation, even if it would otherwise not be detected as translatable text. Same signature as wplng_json_rules_exclusion.

Declaration:

$wplng_data_json_rules_inclusion = apply_filters(
	'wplng_json_rules_inclusion',
	$logical_rules
);

return $wplng_data_json_rules_inclusion;

Usage example:

<?php

add_filter( 'wplng_json_rules_inclusion', function ( $rules ) {
	$rules[] = function ( $element, $parents ) {
		return isset( $parents[0] ) && $parents[0] === 'myPluginData' && isset( $parents[1] ) && $parents[1] === 'i18n';
	};
	return $rules;
} );

HTML Attributes Translation

wplng_attr_json_to_translate

Type: Filter

File: data/attribute.php

Description: Filters the list of { attr, selector } pairs identifying HTML attributes whose value is JSON and must be parsed/translated (e.g. Divi's data-et-multi-view).

Declaration:

$wplng_data_attr_json_to_translate = apply_filters(
	'wplng_attr_json_to_translate',
	array(
		array(
			'attr'     => 'data-et-multi-view',
			'selector' => '[data-et-multi-view]',
		),
		// ...
	)
);

Usage example:

<?php

add_filter( 'wplng_attr_json_to_translate', function ( $rules ) {
	$rules[] = array(
		'attr'     => 'data-my-json',
		'selector' => '[data-my-json]',
	);
	return $rules;
} );

wplng_attr_text_to_translate

Type: Filter

File: data/attribute.php

Description: Filters the list of { attr, selector } pairs identifying HTML attributes containing plain text to translate (alt, title, placeholder, label, ...).

Declaration:

$wplng_data_attr_text_to_translate = apply_filters(
	'wplng_attr_text_to_translate',
	array(
		array(
			'attr'     => 'alt',
			'selector' => '[alt]',
		),
		// ...
	)
);

Usage example:

<?php

add_filter( 'wplng_attr_text_to_translate', function ( $rules ) {
	$rules[] = array(
		'attr'     => 'data-tooltip',
		'selector' => '[data-tooltip]',
	);
	return $rules;
} );

wplng_attr_html_to_translate

Type: Filter

File: data/attribute.php

Description: Filters the list of { attr, selector } pairs identifying HTML attributes whose value is itself HTML markup to translate (e.g. data-sub-html, used by lightbox galleries).

Declaration:

$wplng_data_attr_html_to_translate = apply_filters(
	'wplng_attr_html_to_translate',
	array(
		array(
			'attr'     => 'data-sub-html',
			'selector' => '[data-sub-html]',
		),
	)
);

Usage example:

<?php

add_filter( 'wplng_attr_html_to_translate', function ( $rules ) {
	$rules[] = array(
		'attr'     => 'data-html-caption',
		'selector' => '[data-html-caption]',
	);
	return $rules;
} );

wplng_attr_url_to_translate

Type: Filter

File: data/attribute.php

Description: Filters the list of { attr, selector } pairs identifying HTML attributes containing URLs that must be translated with wplng_url_translate (href, action, canonical <link>, og:url, ...).

Declaration:

$wplng_data_attr_url_to_translate = apply_filters(
	'wplng_attr_url_to_translate',
	array(
		array(
			'attr'     => 'href',
			'selector' => 'a[href]',
		),
		// ...
	)
);

Usage example:

<?php

add_filter( 'wplng_attr_url_to_translate', function ( $rules ) {
	$rules[] = array(
		'attr'     => 'data-href',
		'selector' => '[data-href]',
	);
	return $rules;
} );

wplng_attr_lang_id_to_replace

Type: Filter

File: data/attribute.php

Description: Filters the list of { attr, selector } pairs identifying HTML attributes whose value must be replaced with the current language ID (<html lang>, og:locale, dc.language, ...).

Declaration:

$wplng_data_attr_lang_id_to_replace = apply_filters(
	'wplng_attr_lang_id_to_replace',
	array(
		array(
			'attr'     => 'lang',
			'selector' => 'html',
		),
		// ...
	)
);

Usage example:

<?php

add_filter( 'wplng_attr_lang_id_to_replace', function ( $rules ) {
	$rules[] = array(
		'attr'     => 'data-lang',
		'selector' => '[data-lang]',
	);
	return $rules;
} );

Compatibility & Core

wplng_bypass_multisite_incompatibility

Type: Filter

File: wplingua.php (also referenced in inc/admin/option-page.php)

Description: wpLingua does not officially support WordPress multisite installations. When a multisite is detected, the plugin refuses to bootstrap and displays an admin notice. Returning true on this filter bypasses both the loading guard and the admin notice. This does not make wpLingua officially compatible with multisite · use at your own risk.

Declaration:

// wplingua.php
if ( ! empty( wplng_get_incompatible_plugins() )
	|| ( is_multisite()
		&& ! apply_filters( 'wplng_bypass_multisite_incompatibility', false )
	)
	// ...
) {
	return;
}

Usage example:

<?php

// Force wpLingua to run on a multisite install (unsupported)
add_filter( 'wplng_bypass_multisite_incompatibility', '__return_true' );

wplng_cookie_check

Type: Filter

File: inc/api/translate.php, inc/buffering.php

Description: Before calling the wpLingua translation API or redirecting a page to its translated slug, wpLingua checks for the presence of the wplingua client-side cookie. This avoids sending requests for bots/crawlers that don't execute the front-end JavaScript that sets the cookie. Return false to disable this cookie requirement.

Declaration:

// inc/api/translate.php
if ( empty( $_COOKIE['wplingua'] )
	&& apply_filters( 'wplng_cookie_check', true )
) {
	global $wplng_class_reload;
	$wplng_class_reload = true;
	return array();
}

Usage example:

<?php

// Disable the cookie requirement (e.g. for a caching/headless setup)
add_filter( 'wplng_cookie_check', '__return_false' );

wpLingua · wordpress.org/plugins/wplingua · wpLingua.com · Terms & Conditions

Home

Reference

Classic uses

Recipes

Clone this wiki locally