facetwp_i18n
Overview
Generally, text strings that appear in the UI of your site and in FacetWP will be translatable using __() or _e(). You’d use a translation plugin, or a WordPress gettext filter (see this example).
However, some of the UI strings that appear in various facet types are dynamic, “in-database” strings, which means that WPML or Polylang for example cannot see them directly. The facetwp_i18n filter allows these strings to be translated.
An alternative to using the facetwp_i18n hook would be to transform these UI strings to __() translatable strings, with the facetwp_facet_render_args hook.
This filter can also be used to translate facet labels.
Translatable strings
The following facet types’ strings can be translated with this hook. For an example of how to use it, see below.
| Facet type | Option / string |
|---|---|
| Checkboxes | “See {num} more” / “See less” link text |
| Dropdown facet | Default label |
| Radio facet | Default label |
| fSelect facet | Default label |
| Hierarchy facet | Default label “See {num} more” / “See less” link text |
| Slider facet | Reset text Prefix Suffix Slider handles’ aria-labels |
| Search facet | Placeholder text |
| Autocomplete facet | Placeholder text |
| Date Range facet | Placeholder texts. Note: the Date Range facet’s calendar can be translated with the facetwp_render_output hook. |
| Star Rating facet | “& up” and “Undo” link texts |
| Proximity facet | Placeholder text Unit of measurement label (“km” or “mi”) in the radius dropdown/slider |
| Pager facet | See this example |
| Type: Page numbers | Dots label Prev button label Next button label |
| Type: Result counts | Count text (plural) Count text (singular) Count text (no results) |
| Type: Load more | Load more text Loading text |
| Type: Per page | Default label “Show all” text (if a non-numeric option is added in the settings) |
| Sort facet | Default label All sort option labels |
| Reset facet | Reset text |
| Map facet | “Enable map filtering” button text “Reset” button text |
| Hierarchy Select facet | Depth labels |
| Range List facet | Default label |
| Time Since facet | Choices labels Default label |
| A-Z Listing | Default label |
| Color | “See {num} more” / “See less” link text |
| All facet types | Facet labels (which appear as headings in the Mobile Flyout and as labels in the User Selections facet). See below for an example. |
Additionally, the following Listing Builder item can be translated:
| Item | Option / string |
|---|---|
| Button | Button item text |
Parameters
- $string | string | The string to translate
Usage examples
Translate UI strings
To translate one or more of the UI strings listed above, add the following code (adapted with your translated strings) to your (child) theme’s functions.php.
In this example, the default language is English and the code gives translations for 2 strings, for the 2 non-default languages, in this case Spanish (‘es’) and German (‘de’). You should only list the non-default language(s), and use the strings as used in the default language (in this case the English ‘Any’ and ‘Enter keywords’). These are the strings as they are set by default in FacetWP’s code, or in each facet’s settings (for example the Placeholder text you can set in the Search facet’s settings).
Also important for this to work is that any strings you set in your facets’ settings are in the default language. Last but not least: the strings need to match exactly, including capitalization and spaces.
How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_i18n', function( $string ) { if ( isset( FWP()->facet->http_params['lang'] ) ) { $lang = FWP()->facet->http_params['lang']; $translations = []; $translations['es']['Any'] = 'Cualquier'; $translations['de']['Any'] = 'Jeder'; $translations['es']['Enter keywords'] = 'Introduzca las palabras clave'; $translations['de']['Enter keywords'] = 'Geben Sie Schlüsselwörter'; if ( isset( $translations[ $lang ][ $string ] ) ) { return $translations[ $lang ][ $string ]; } } return $string; });
An alternative to using the facetwp_i18n hook would be to transform these UI strings to __() translatable strings, with the facetwp_facet_render_args hook.
Translate facet labels
Besides translating UI strings, the facetwp_i18n filter can also be used to translate facet labels. The facet label is the label you give it when creating it (not to be confused with the facet’s name, which is its technical name):
The facet label appears as facet heading in the Mobile Flyout and as label in the User Selections facet).
Translating facet labels works the same as translating UI strings. Here is an example for a facet with label “Size” in the default English language, which is translated to “Maat” when the page is viewed in the Dutch language. Note that the label needs to match exactly, including capitalization and spaces:
How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_i18n', function( $string ) { if ( isset( FWP()->facet->http_params['lang'] ) ) { $lang = FWP()->facet->http_params['lang']; $translations = []; $translations['nl']['Size'] = 'Maat'; if ( isset( $translations[ $lang ][ $string ] ) ) { return $translations[ $lang ][ $string ]; } } return $string; });
Don’t confuse translating facet labels with translating facet choices:
Translate facet choices
There are multiple ways to translate facet choices. The best way is to translate the content of the data source field that the facet uses. For example, if your facet uses a taxonomy as data source, you can translate the taxonomy terms with WPML, or with Polylang.
If your facet uses a custom field as data source, just translate that custom field. For WPML see this tutorial. Or, for facets using a custom field created with Advanced Custom Fields, use the ACF Multilingual plugin. For Polylang, see this page for how to translate ACF fields.
Alternatively, you can translate facet choices manually. You can use the facetwp_facet_display_value hook, or the facetwp_facet_render_args hook. With this last hook, you can change specific or all facet choice labels into __() translatable strings. These can then be translated with a translation plugin or a gettext filter.
Use the facetwp_i18n hook without the Multilingual add-on
If you are not using WPML or Polylang (with the FacetWP Multilingual add-on), you can still use the facetwp_i18n hook. You only need a way to detect the current language of the page (or site if you are using a multi-site setup).
The following code example gets the language from the current page/site with WP’s get_locale() function:
How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_i18n', function( $string ) { // Get the current site's locale $lang = get_locale(); $translations = [ 'fr_FR' => [ 'All categories' => 'Toutes les catégories', ], ]; if ( isset( $translations[ $lang ][ $string ] ) ) { return $translations[ $lang ][ $string ]; } return $string; });