facetwp_i18n
Overview
With this hook you can manually translate all of FacetWP’s dynamic strings, and some of its static strings. It can also be used to translate facet labels.
Generally, there two types of strings that can appear in your site: static strings and dynamic strings:
Translate static strings
Static strings are the strings that appear in plugin/theme code surrounded by __(), and have a “language domain”. For example: __( 'No results', 'fwp-front' ). FacetWP uses two language domains: fwp for internal/admin strings, and fwp-front for front-end strings.
To translate these kinds of strings, you need to use the .po/.mo language files of the theme/plugin. In practice, the best way to handle this is to install the Loco Translate plugin. If you are using WPML, the recommended way is to use the WPML String Translation add-on instead, as it handles both static and dynamic string translation. For Polylang, Loco Translate is the recommended way, because it does not handle static string translation.
Alternatively, or additionally, if you prefer to translate (certain) static strings in code, you can also use the gettext_{$domain} WordPress filter, as shown in this example.
Translate dynamic strings
Dynamic strings come from plugin/theme settings and are stored in the database. An example would be a facet’s “Default label” (e.g. “Any”), as set in, for example, a Dropdown facet’s settings.
When using WPML or Polylang, with the Multilingual add-on, some of FacetWP’s dynamic strings are automatically registered, so they can be translated in WMPL’s String Translation section, or Polylang’s Languages > Translations section. At the time of writing, not all of FacetWP’s strings are registered that way though. In a future update, we will add all of them.
The facetwp_i18n hook can be used to translate all of FacetWP’s dynamic strings, as listed below.
This hook also runs for some static strings, which makes them translatable in both ways.
It is also possible to convert dynamic strings to static strings using the facetwp_facet_render_args hook, so that they can be translated with Loco Translate or gettext(), as well as with the facetwp_i18n hook.
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 |
| Exclude | Default label “See {num} more” / “See less” link textPrefix Suffix |
| 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. |
The following Listing Builder item can be translated:
| Item | Option / string |
|---|---|
| Button | Button item text |
The following Elementor FacetWP widget item can be translated:
| Item | Option / string |
|---|---|
| Facet widget | Facet Header 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; });