Facetwp Multilingual Addon v1.0.2

If you are using WPML, Polylang or Polylang Pro, download and install the Multilingual add-on to integrate your translations with FacetWP. Note:Make sure all your posts have a (default) language set, as the Multilingual add-on only indexes/displays results “tagged” with the currently active language. WPML The Multilingual add-on supports normal translations, as well as dynamic strings (e.g. facet placeholder text) via the WPML String Translation plugin.

The add-on supports sub-site (fr.mysite.com) and sub-directory (mysite.com/fr/) permalinks, but does not support URL strings (?lang=fr). WPML translation setup In order for WPML to work well with FacetWP, you need to correctly set up the Post Types Translations and Taxonomies Translations in WPML’s settings. Go to: WPML > Settings > Multilingual Content Setup Then scroll down to the “Post Types Translation” and “Taxonomies Translations” tables.

For each post type and taxonomy that you are using in post listings with facets, make sure you select the first option: “only show translated items”: WPML Post Types and Taxonomies Translation setting – Select “Only show translated items”. Do not use the second (fallback) option! Then, in WPML > Translation Management and WPML > Taxonomy translation, make sure every item has a translation.

Or you can use the bulk edit feature to create duplicates for all items, for as long as the content is not translated yet. The second option, “use translation if available or fallback to default language”, does not work well with FacetWP. If you select that option and you have posts without a translation, you will have the fallback (original language) posts in the translated language results, and those posts will have their (original language) categories/terms indexed.

This will result in duplicate categories/terms showing up in facets: in the translated language and in the original language. Keep in mind that when FacetWP indexes a post, it determines that post’s language and indexes any related content for that language. FacetWP does not support the concept of a single post belonging to multiple languages, so you essentially need to have a translated post for each language.

If a translation is not available, you need to duplicate the post in the original language. If you are using (ACF) custom fields as data source for your facet, make sure that those fields are set to be translatable, and are translated for each post in each language. Note:As described above, when the Multilingual add-on is active, FacetWP expects posts to have a language.

If you have facets on a listing with posts that have no language set, filtering will lead to no results. Depending on your setup, you may be able to solve this by preventing FacetWP from from using the current language when filtering. Solving issues with WPML If you encounter any issues with WPML, like posts, terms or other data not appearing, make sure your WordPress install has enough memory.

WPML’s minimum requirements are 128M, and 256M is recommended. In our performance tuturial you can read how to give WordPress more memory. You can see how much memory is currently set by going to WPML > Support. In the WordPress section, you’ll see what is set as WordPress’ memory limit. This has to be lower or equal to what is available on the server, which you can see in the PHP section under “Memory limit”.

If you go to WPML > Support > Troubleshooting, you’ll see a lot of buttons with which you can clean up WPML’s cache and database. Make sure you have a database backup before using that. Polylang The Multilingual add-on supports normal Polylang translations. Make sure to go through all configuration steps of the setup wizard, which is automatically launched when activating Polylang or Polylang Pro for the first time.

In this process, one or more languages are assigned to your content. If you skip(ped) this step, then your existing content does not have a language set, which causes posts to not show up in your template’s query. You can fix this by running the wizard again, or assigning a language in bulk. Note:As described above, when the Multilingual add-on is active, FacetWP expects posts to have a language.

If you have facets on a listing with posts that have no language set, filtering will lead to no results. Depending on your setup, you may be able to solve this by preventing FacetWP from from using the current language when filtering. Don’t use Polylang Pro’s shared slug feature Polylang Pro comes with a feature that makes it possible for posts, pages or terms to share the same slug across translations.

Currently, this feature does not work with FacetWP. With shared slugs, on pages with the non-default language facets will not return expected options. The solution for now is to use unique slugs across translations. Using WPML or Polylang with SearchWP If you are using SearchWP on a multilingual site with WPML or Polylang, make sure to install the appropriate SearchWP integration extension: SearchWP WPML integration extension SearchWP Polylang integration extension These extensions will limit search results to the active language of the page.

Without them, there will be a disconnect between the facets, their counts and the post listing. Translate UI strings and facet labels with the facetwp_i18n filter hook Generally, text strings that appear in the UI of your site and in FacetWP will be translatable using __() or _e(). You’d use your 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 cannot see them. Fortunately, there is a way to translate these strings: with the facetwp_i18n filter hook. This filter hook can also be used to translate facet labels. Note that facet labels are something different than facet names.

Facet labels appear as facet heading in the Mobile Flyout and as label in the User Selections facet). Also don’t confuse facet labels or names with 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. Fix indexing errors with Polylang or WPML installed When you have Polylang or WPML installed without the Multilingual add-on, you can get a “The index table is empty” error when trying to re-index.

To fix this, simply install the add-on and re-index. Fix issues with filtering posts with no language set WPML and Polylang automatically query only posts for the current language. When the Multilingual add-on is active, FacetWP also expects posts to have a language. It gets the current language from the page and stores it in the FWP_HTTP['lang'] parameter in order to remember it during facet refresh, and filter only the posts in this language.

There are some scenarios in which this language parameter causes unexpected filtering issues, like empty facets or no results after filtering. You may for example have a listing template that queries a custom post type with no language set for its posts, on which you are effectively not using WPML or Polylang. Or you may have an archive in which you want to retrieve and filter posts of all languages.

In these situations, you need to prevent FacetWP from using the current language when filtering. To remove the language parameter from FacetWP’s AJAX refresh, add the following snippet to your (child) theme’s functions.php: 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 infoadd_action( 'facetwp_scripts', function() { // Use the correct conditional for your template(s), e.g. is_archive(), is_page(), is_category() etc. // See: https://codex.wordpress.org/Conditional_Tags if ( is_post_type_archive( 'my_custom_post_type' ) ) { ?> facet->http_params; if ( isset( $http['lang'] ) ) { do_action( 'wpml_switch_language', $http['lang'] ); } return $args; }, 11 ); Users that report this issue are most often logged-in when seeing it, and are switching between languages in the back-end admin and the front-end, in the same browser. The front-end language then sometimes incorrectly takes on the admin language. The above snippet forces WPML to always switch the language to the one FacetWP is using in the front-end.

Fix cron indexing issues when using WPML and Post Types Order Note:The issue as described below was fixed in version 4.3.4. There is a known issue when using FacetWP with WPML and the Post Types Order plugin, when using cron indexing (for example with the Schedule Indexer add-on). The issue causes only a single language to be indexed, resulting in posts disappearing from indexed rows and facet options.

This issue only happens when the “Auto Sort” setting in Post Types Order is enabled. We are working on a fix. In the meantime, disable “Auto Sort” to fix the issue: Disable “Auto Sort” to prevent cron indexing issues when using WPML. If needed, manually add 'orderby' => 'menu_order' to your WP_Query arguments. Using a facet’s “Parent term” setting in a multi-lingual setup The “Parent term” setting, available in Checkboxes, Dropdown, fSelect, Radio, and Color facets.

If you have a facet using a taxonomy as data source, and want to use its “Parent term” setting to display only child terms of a specific parent term, you’ll notice that this does not work in a multi-lingual setup. This is because in translated taxonomies, the term ID of the parent term you want to use will be different for each language. There are two ways to solve this: Create separate facets for each language, and set the “Parent term” to the correct term ID for the language.

Keep using one facet, but let it index the children of the parent IDs of all languages, using the facetwp_index_row hook. If you choose to use the linked snippet, do not set a parent ID in the “Parent term” setting. Also make sure to re-index after adding or changing the snippet. After re-indexing, the facet will show the children of the correct parent term on each language page, because it will only show choices for which there are posts in the listing.

Note that the “Parent term” setting is only available in Checkboxes, Dropdown, Radio, fSelect, and Color facets. Changelog 1.0.1Feb 4, 2022 Fixed minor code cleanup / modernization 1.0.0Sep 21, 2020 Fixed the correct element_type was not being passed into WPML (props Bram) 0.2.2Aug 12, 2020 Fixed reset WPML language after indexing Fixed make sure Polylang language variable is defined 0.2.1Sep 5, 2018 Fixed WPML class name (props Derrick Hammer) See also Using the facetwp_i18n hook to translate facet labels and strings Using FacetWP with SearchWP Indexing Facet types What are facets? The facetwp_facet_display_value hook The facetwp_facet_render_args hook Using FacetWP with Advanced Custom Fields The facetwp-refresh event Using FacetWP with Post Types Order The Schedule Indexer add-on Last updated: October 24, 2025