FacetWP Multilingual - WordPress Plugin

FacetWP Multilingual Setup Guide for Multilingual Filtering

FacetWP Multilingual is not meant to translate your entire site on its own. Its job is to make FacetWP work correctly on a site that already uses WPML or Polylang. In this guide, we will walk through how to prepare your content, enable the add-on, configure languages, test facets across different language versions, and avoid ending up with empty results after the first filter is applied.

The main challenge here is not installing the ZIP file. On a multilingual site, filtering depends on several layers at once: the post language, taxonomy translations, custom field translations, the listing query, the FacetWP index, AJAX refreshes, and the page URL. If one layer is configured as a fallback while another expects a separate post in the current language, the result can look like a plugin bug even though the real cause is usually the translation structure.

This guide is written for a site owner or developer who already uses FacetWP together with one of the supported multilingual plugins. Below you will find a basic installation path, detailed setup steps for WPML and Polylang, a catalog implementation example, result checks, a troubleshooting block, and a comparison with similar solutions.

What problem this add-on solves in a multilingual FacetWP setup

FacetWP builds filtering around a listing. The listing receives a set of WordPress posts, and the facets let visitors narrow that set by taxonomies, custom fields, price, rating, date, search query, or another data source. On a single-language site, this is relatively straightforward: FacetWP indexes the data, the AJAX request refreshes the results, selected values are added to the URL, and the page shows only matching posts.

On a multilingual site, language becomes part of that chain. A Russian post, its English version, a translated category, a translated ACF field value, and a placeholder string in a search facet are not the same object to WordPress. WPML and Polylang help connect those objects across languages, but FacetWP still needs to understand which language is currently active and which posts can be shown in the current listing.

FacetWP Multilingual connects FacetWP with WPML or Polylang so that the index and the results respect the current page language. The add-on does not replace your translation plugin, does not create translations automatically, and does not repair an incomplete language structure. Its role is narrower: pass the language context to FacetWP and keep values from different languages from being mixed together in one result set.

A typical example is a course catalog in two languages. The category "Design" is translated, several courses already exist in both languages, but some still exist only in the default language. Without careful setup, a user may see English categories on the Russian page, get an empty list after selecting a filter, or see duplicate terms inside a facet. That does not automatically mean FacetWP is broken. Very often, it is a consequence of the translation plugin allowing a fallback while FacetWP expects a separate post marked with the active language.

What the add-on does not do

It is important to set expectations early. FacetWP Multilingual is not a standalone interface translator, does not provide machine translation, and does not translate field values instead of WPML or Polylang. If the facet source is a taxonomy, the terms must be translated using the standard WPML or Polylang tools. If the source is an ACF field, that field needs an appropriate translation rule. If a string lives in the database and is not visible to the translation plugin, it needs to be handled through the documented facetwp_i18n filter or another official mechanism.

There is another limitation as well: multilingual support does not cancel the general FacetWP rules. The page still needs one FacetWP-compatible listing, facets still need correct technical names, the index still needs to be rebuilt after facet or data source changes, and conflicting queries or overly complex listings still require troubleshooting. The add-on adds a language layer, but it does not make your site architecture limitless.

Who this setup is for, and when another path makes more sense

FacetWP Multilingual is a strong fit for sites where FacetWP is already the primary filtering engine and multilingual support is built with WPML or Polylang. That includes service directories, knowledge bases, product catalogs, courses, job listings, events, recipes, expert profiles, portfolios, and any other pages where visitors need to narrow a list quickly in their own language.

The best-case scenario is a project with clear language discipline. Each language has its own posts or translations, taxonomies are kept in sync, custom fields are marked in advance as translatable, copied, or independent, and the URL structure is not changed casually after launch. In that environment, FacetWP Multilingual delivers predictable results: the visitor opens a language-specific page, sees facets with localized terms, and gets results only in the expected language.

The add-on may be unnecessary if the site does not use WPML or Polylang. FacetWP documentation describes a separate path for some strings through facetwp_i18n without the Multilingual add-on, but that is not a full replacement for language integration. That approach only fits edge cases: one site, custom locale handling, a few dynamic labels, and no proper translation structure.

There is an opposite case too. If the site is built around an external search service, contains millions of posts, depends heavily on Elasticsearch or Algolia, or requires separate search logic for each language, FacetWP can still remain part of the solution, but it will not always be the only search core. FacetWP documentation openly notes that MySQL has natural limits, and specialized search engines are a better fit for some scales and search patterns.

When to stop before installing it

Do not start by installing the add-on if the site does not yet have a basic language structure. First, you need to know which post types are translated, which taxonomies are used in facets, which custom fields become filter sources, where the listing lives, which pages are shared across all languages, and which ones are separate. If posts do not have a language assigned, FacetWP Multilingual will not be able to show them as normal results for the current language version.

It is also worth postponing setup if the site mixes several translation plugins. Polylang explicitly warns in its documentation that if you are moving from another multilingual solution, the old plugin should be deactivated before activating Polylang, otherwise unexpected results are possible. For FacetWP, this is especially important: the index is built from the current WordPress state, and mixed language metadata creates errors that are difficult to explain.

What to check before installation and the first indexing run

Preparation before installation should answer one question: when FacetWP indexes the site, will it be able to determine the language of every post and every value that enters a facet without ambiguity? If the answer is unclear, installing the add-on will only expose the problem faster.

Existing posts must already have a language assigned

For both WPML and Polylang, it is critical that the posts used in the listing have a language assigned. In Polylang, this is often handled by the setup wizard or by bulk assigning a language to existing content. If that step is skipped, the listing may return no posts at all, and after selecting a filter the visitor may see empty results. WPML follows similar logic: a post without a valid language state cannot reliably participate in language-specific results.

Do not check only standard posts. In real FacetWP projects, custom post types are often filtered instead: products, properties, courses, events, jobs, specialists, documents. For each of those types, verify that it is enabled in the translation plugin, that translations are being created, that there are no old posts without a language, and that the post type is not excluded from indexing.

Taxonomies and terms must be translated

If a facet is built from categories, tags, WooCommerce attributes, or a custom taxonomy, you need to translate not just the posts but also the terms themselves. Otherwise, the user may see mixed labels, incomplete values, or a facet missing the options they expect. For WPML, FacetWP officially recommends configuring post type and taxonomy translations so that only translated items are shown instead of falling back to the default language.

Pay extra attention to hierarchical taxonomies. If one language has a parent term and its translation in another language has a different ID, the Parent term setting in some facets may not behave the same way it does on a single-language site. FacetWP explains this by pointing out that the parent term ID differs across languages. That means for a multilingual catalog, it can be better to create separate language-specific facets, adjust the taxonomy structure, or use a documented hook with mandatory re-indexing.

Custom fields need their own strategy

Many of the strongest FacetWP use cases are built not on categories but on ACF, Meta Box, Pods, or custom meta fields. Here, you cannot simply assume the translation plugin will guess the right logic. Text values usually need translation. Numbers, IDs, ratings, dates, prices, and technical values often need synchronization or copying. Images and relationships may use separate modes, depending on WPML or Polylang Pro.

A bad example is a difficulty field where English posts contain Beginner, but the Russian copies are left empty. The facet will honestly index what exists in the database, and the Russian page will not be able to display proper values. A better approach is to decide in advance whether the value will be translated into the Russian equivalents of "Beginner," "Intermediate," and "Advanced," or stored as a technical code such as beginner while the display label is translated separately.

The listing should be single and clearly defined

FacetWP requires a FacetWP-compatible listing on the page. The documentation emphasizes that there should be only one active FacetWP-enabled listing per page. If the page contains several similar lists, one created with blocks, one output by the theme, and a third added by a builder, the filter may attach to the wrong query. On a multilingual site, this becomes even more confusing because each list may carry its own language context.

Before installation, check the page the way a normal user would: does the language version open correctly, does it show the right posts before any filter is applied, are there multiple facetwp-template containers in the source, and is the theme replacing the main query with a custom query. If the listing itself is wrong, FacetWP Multilingual will not fix its language layer.

Installation, activation, and a safe first test

Installing FacetWP Multilingual is usually simple: download the add-on from your FacetWP account, install it like a regular WordPress plugin, and activate it. The important thing to understand is that this is an add-on for FacetWP. It has no value without the main FacetWP plugin and without WPML or Polylang on the site. The official add-ons page lists Multilingual under integrations and describes it as an integration with WPML or Polylang.

Activation order

1. First, make sure the main FacetWP plugin is installed, activated, and working on a single-language page or in the default language.
2. Confirm that WPML or Polylang is already configured and that languages are assigned to the existing content.
3. Install FacetWP Multilingual through Plugins in the WordPress admin panel.
4. Open Settings > FacetWP, save the facets used on the multilingual page, and run Re-index.
5. After indexing finishes, open the listing page in each language in a separate window while logged out of the admin area.

For the first test, do not try every facet at once. Start with one obvious scenario. For example, choose a category that definitely has posts in both Russian and English. If the filter works in one language but returns nothing in the other, do not jump into code right away. First, check the post translations, the term translation, the WPML or Polylang settings, and whether that page exists in the target language.

Safe rule: after enabling the add-on, do not change the URL structure, field translations, listing settings, and theme code all at once. Make one change at a time, re-index FacetWP, and test the result on a specific language page.

How to tell the installation worked

The minimum successful result looks like this: on the default-language page, facets show values in that language; on the second language page, they show values in the second language; and selecting one value does not pull in posts from the other language version. When a facet is selected, the FacetWP URL will get a query string such as ?_category=value or similar variables, but the page itself should stay in the correct language section, for example with a language subdirectory or subdomain if that is how WPML is configured.

If you use WPML, pay attention to the URL format. FacetWP documentation states that the add-on supports language subdomains and subdirectories, but does not support the ?lang=fr URL-string approach. So if your site uses that mode, it is better to rethink the language structure up front instead of trying to patch each facet individually.

WPML setup: translated items instead of fallback content

WPML offers a flexible translation model, but that flexibility is exactly what often creates FacetWP errors. The official FacetWP guide recommends choosing the mode that shows only translated items for the post types and taxonomies used in facets. The option that says "use translation if available or fallback to default language" works poorly with FacetWP because FacetWP indexes the post language and its related data for that language.

The logic is simple: FacetWP does not treat one post as if it belongs to several languages at the same time. If a post is not translated, it needs to be translated or temporarily duplicated through WPML. Otherwise, a facet on a translated page may pull in posts from the default language together with their original categories and terms. That is where duplicate categories, mixed labels, and strange facet counts come from.

Where to configure it in the admin panel

In WPML, the relevant setting is under WPML > Settings > Multilingual Content Setup. There, check the Post Types Translation and Taxonomies Translations tables. For the post types and taxonomies used in the FacetWP listing, choose the mode that shows translated items only. Then review WPML > Translation Management and WPML > Taxonomy translation to make sure posts and terms have either real translations or intentional duplicates.

If a facet uses an ACF field or another custom field, WPML also needs a translation rule for that field. Text values that visitors see as facet choices usually need translation. Numeric or technical values are often copied. There is no universal answer, but the practical test is simple: the value FacetWP filters by must exist and be correct in every language.

Dynamic strings and facet labels

WPML String Translation can translate dynamic strings such as a search facet placeholder. But FacetWP documentation also notes that some strings are stored in the database and may not be directly visible to WPML or Polylang. For those strings, there is the facetwp_i18n filter. It is useful for labels, placeholders, reset text, loading text, labels in User Selections, and other interface elements listed in the official documentation.

Use the filter carefully. The source string must match exactly, including capitalization and spaces. If the facet placeholder is saved as Enter keywords but the code looks for Enter Keywords, the translation will not work. That is why it is better to standardize the labels in the FacetWP settings first, then add exact translations.

add_filter( 'facetwp_i18n', function( $string ) {
    if ( isset( FWP()->facet->http_params['lang'] ) ) {
        $lang = FWP()->facet->http_params['lang'];

        $translations = [];
        $translations['ru']['Any'] = 'Any';
        $translations['ru']['Enter keywords'] = 'Enter keywords';
        $translations['de']['Any'] = 'Alle';
        $translations['de']['Enter keywords'] = 'Suchbegriffe eingeben';

        if ( isset( $translations[ $lang ][ $string ] ) ) {
            return $translations[ $lang ][ $string ];
        }
    }

    return $string;
} );

It is better to add code like this to a child theme, a snippet plugin, or the official FacetWP Custom Hooks add-on, not to the main plugin files or the theme core. Rolling it back is simple: disable the snippet, clear the page cache, and re-index FacetWP if you changed not only interface strings but also data sources.

Memory, support, and the admin language

WPML has its own WordPress memory requirements. If posts disappear, the indexer stalls, or terms fail to appear after enabling WPML, FacetWP, and the Multilingual add-on, check the memory limit through WPML > Support and Tools > Site Health. FacetWP documentation specifically mentions that when WPML-related issues appear, you should verify available memory and, if needed, run WPML maintenance through WPML > Support > Troubleshooting, after making a database backup.

There is also a subtler issue: the user logs into the admin area, switches the admin language, and tests the front end in the same tab or browser. FacetWP describes a case where the listing and facet language appears to change randomly. For that scenario, the documentation provides a facetwp_query_args hook that forces WPML to switch to the language used by FacetWP on the front-end page. Only add that code if the symptom truly matches and the basic WPML setup has already been verified.

Polylang setup: languages, unique slugs, and content structure

With Polylang, the logic is similar: FacetWP Multilingual supports standard Polylang translations, but it expects the content to have a language assigned. If the Polylang setup wizard was skipped during the initial setup, existing posts may remain without a language. In that state, the FacetWP listing often shows nothing or loses posts after AJAX filtering.

Start in Languages > Languages and review the language list, codes, locales, and URL structure. Polylang uses the language to build URLs, resolve translations, and display the language switcher. The language code must be unique, and changing it on a live site also changes the URLs of related posts, which can break old links if redirects are not in place.

Assigning a language to existing content

If the site existed before Polylang was added, do not stop after creating languages. Assign a language to old posts, products, pages, media items, and custom post types that appear in FacetWP. For large catalogs, this is best done on a copy of the site or after a backup, because language metadata will become part of all subsequent queries.

Check the result in a simple way: open the post list in the admin area, enable the language columns, and make sure each post has the expected language. Then open the public page for a given language without selecting anything in FacetWP. If the list is already empty, the problem is not the facet but the base language query.

Why shared slugs in Polylang Pro are better disabled for FacetWP

Polylang Pro can assign the same slug to translations. For a regular page, that may look clean, but the official FacetWP documentation explicitly warns that the shared slug feature in Polylang Pro does not currently work with FacetWP and causes problems. Symptoms include facets on non-default language pages failing to return the expected options, and blog archives breaking if pages in different languages share the same pagename or slug.

The practical takeaway is this: for pages and terms used by FacetWP, use unique slugs across translations. It may look slightly less elegant, but WordPress and FacetWP will be able to determine the page type, language, and query without ambiguity. If shared slugs are already enabled, document the current URLs first, prepare redirects, disable the shared slug for the affected objects, then re-index FacetWP and retest the facets on language-specific pages.

ACF and Polylang Pro

If your facet sources come from ACF, follow the Polylang documentation for ACF Pro support. In newer workflows, Polylang Pro allows labels, instructions, and field values to be translated through its own settings, and field behavior can vary: ignore, copy once, translate, translate once, or synchronize. For FacetWP, this is not an abstract preference. It directly affects the values that enter the index.

For a text field displayed as a facet choice, translation is usually the right option. For relationships, images, and structural data, copy once or synchronize may make more sense. For fields that should not participate across all languages, ignore is appropriate. The key is not to mix language-specific labels and technical values inside one facet without a plan. After changing field behavior, review the existing translations and re-index FacetWP.

How to translate facet labels, choices, and source data

In multilingual filtering, there are three different layers of text. The first is the technical facet name that appears in the shortcode and the URL. The second is the facet label that may appear in the interface. The third is the choices, meaning the values the visitor selects: categories, colors, sizes, cities, material types, difficulty levels. These layers should not be mixed.

The technical facet name should be short, Latin-based, and stable. FacetWP documentation explains that the name is used in the URL and JavaScript, sanitized for unsafe characters, and stripped of non-Latin characters. So do not name a facet color in a non-Latin language or something like course_category in a non-Latin script. Use color, course_category, or difficulty instead. The user does not need to see that name, but the URL and AJAX layer will be more reliable.

Facet labels are translated separately from facet names

The label is the visible caption. It may appear as a heading in the Mobile Flyout or as a label in User Selections. For these strings, use facetwp_i18n or the translation mechanism if the string is accessible to WPML or Polylang. Do not rename the technical facet name just to translate the label. That creates new URL variables and can break existing links with preselected values.

Choices are best translated in the data source itself

The best way to translate choices is to translate the source data. If the source is a taxonomy, translate the terms in WPML or Polylang. If the source is a custom field, translate the field value or assign the correct field behavior. FacetWP does allow manual replacement of displayed values through hooks such as facetwp_facet_display_value, facetwp_facet_html, or facetwp_facet_render_args, but that is already a technical layer that needs to be maintained and tested after updates.

For most sites, a better rule is this: data is translated where it is created, and FacetWP simply filters it and displays the result. A hook is appropriate when a string is dynamic, stored in the database, invisible to the translation plugin, or when you need a temporary fix for a small interface gap.

URL structure, SEO, and indexable combinations

FacetWP adds selected values to the query string with an _ prefix. That makes it possible to share a link to an already filtered page, use the browser back button, and open a filter combination directly. On a multilingual site, the base URL should remain language-specific, and FacetWP parameters are added on top of that.

Do not try to turn every filter into pretty permalink segments. FacetWP documentation explains that pretty permalinks quickly stop making sense for multiple facet combinations and can harm SEO because they create too many URLs with near-duplicate content. That matters even more in a multilingual catalog: build a stable language structure first, then use clear query variables instead of trying to hide every selection inside the URL path.

Practical example: a bilingual course catalog with filters

Imagine a school website with a custom post type called course, taxonomies course_topic and course_level, and ACF fields duration and format. The goal is to create Russian and English catalog pages where visitors can filter courses by topic, level, and format, while a search facet looks through the title and description.

Goal

On the Russian page, the user should see the Russian equivalents of "Design," "Marketing," and "Development," along with translated level labels, and only Russian course cards in the results. On the English page, the user sees "Design," "Marketing," "Development," "Beginner," and "Advanced" and gets English course cards. The page URL stays language-specific, while selected facets add FacetWP parameters.

Preparation

1. In WPML or Polylang, enable translation for the course post type and the course_topic and course_level taxonomies.
2. Translate or duplicate all course posts that should appear in both languages.
3. Translate the taxonomy terms and verify that each post is linked to the term in its own language.
4. For the ACF field format, choose translation if the values should be localized, or use a technical code plus a separate display translation if that matches the project structure.
5. Create one catalog page per language, or translate the existing page through the multilingual plugin you selected.

Steps in FacetWP

Create a facet for course topic, a facet for level, a facet for format, and a search facet. Keep the technical names in Latin characters: topic, level, format, course_search. Labels can be created in the default language first and then translated through WPML, Polylang, or facetwp_i18n. After saving each facet, run Re-index.

For the listing, choose a method already supported by FacetWP: a WordPress archive, a custom WP_Query, Listing Builder, blocks, or a page builder with an official add-on. The page should contain only one active listing. If the builder includes multiple grids, leave just one active for FacetWP and make the others static or move them to another page.

Verification

Open the Russian page in an incognito window. Select the Russian equivalents of "Design" and "Beginner." The results should now contain only Russian courses with those values. Copy the URL and open it again: the selected values should be restored. Then repeat the same check on the English page. If the English page shows Russian terms, the choices were either not translated at the source or they entered the index through fallback posts.

One caveat

If some courses are not translated yet, do not enable fallback for the post types and taxonomies filtered by FacetWP. It is better to temporarily duplicate the post into the target language or hide it from translated results. That way, you avoid mixed terms and show visitors only content that truly belongs to the current language.

Result checks, indexing, and performance

FacetWP is fast not because it scans the entire site on every request, but because it builds its own index table. That table stores the relationship between the facet, the value, and the post. On a multilingual site, the index has to reflect the language structure, so after changing translations, taxonomies, field sources, or hooks, you cannot rely on an old index.

When to run Re-index

Re-indexing is required after adding facets, changing facet settings, changing term hierarchies, changing term custom fields, adding hooks that affect the index, changing registered post types, clearing the index table, or fixing indexing issues. During normal post editing, FacetWP may keep the index updated automatically, but a bulk import, translation of an older catalog, or field changes often require a manual action.

For a multilingual project, it helps to keep a short checklist after every major change:

• Save the translation plugin settings.
• Check the language on several old and new posts.
• Verify translations for the terms used in facets.
• Save the facets in Settings > FacetWP.
• Run Re-index and wait for it to finish.
• Open the language-specific pages while logged out of the admin area and walk through one real filtering scenario.

What to review in the results

Your testing should be specific. It is not enough to say "the filter works." Check that the facet shows only values from the current language, the counts do not hint at posts from another language, the selection is preserved in the URL, the reset button returns the listing to its original state, sorting and pagination do not lose the language, and the search facet does not search through another language unless that is intentional.

If caching plugins, a CDN, or JavaScript optimization are enabled, test AJAX behavior after clearing the cache. FacetWP has separate documentation for cache integrations and recommendations, but for multilingual setups the main rule is simple: do not cache one language response as if it were valid for every language. If the Russian page suddenly shows English HTML after filtering, disable optimization and caching first for testing, then re-enable them one by one.

Performance in large catalogs

The more languages you add, the more posts, terms, and values end up in the index. FacetWP can handle large datasets, but the documentation makes it clear that the outcome depends on the server, the number of posts, the number of facets, WooCommerce variations, custom fields, and the number of choices. On heavier sites, it helps to limit which post types are indexed, avoid unnecessary facets, avoid outputting thousands of choices unless they are truly needed, and schedule re-indexing during quieter periods.

If the site imports translations frequently, you may want to consider WP-CLI or cron-based indexing according to the official FacetWP documentation. That is already an engineering-level setup, though. For a small or medium catalog, a manual Re-index after structural changes plus a careful automatic indexer is usually enough.

Special cases: WooCommerce, SearchWP, and hierarchical terms

Multilingual filtering rarely exists in isolation. On a real site, FacetWP often works alongside WooCommerce, ACF, SearchWP, a page builder, product imports, and custom taxonomies. FacetWP Multilingual does not override the rules of any of those layers. It simply helps FacetWP respect the current language, while all other dependencies still need to be configured so they return the correct data.

WooCommerce attributes and products in multiple languages

If FacetWP filters WooCommerce products, check not only the product cards but also attributes, variations, product categories, stock status, and catalog visibility. An attribute like "Color" in English and its translated equivalent in Russian may be handled either as a taxonomy or as a custom field, depending on how the store is built. For FacetWP, what matters is the real data source: what exactly is used as the facet source and which values are actually indexed.

Performance matters especially with variable products. FacetWP notes in its speed documentation that WooCommerce variations increase index weight because each variation may be indexed separately. On a multilingual store, this becomes even more visible: the number of languages multiplies the number of product entities, and every attribute filter adds more rows to the index. If the store does not show variations as separate results, review the FacetWP settings for variation support and out-of-stock indexing. Do not enable heavy modes just in case.

A practical store test should include four actions. First, open a product category in the default language and choose one attribute. Then open the translated version of the same category and choose the translated attribute. After that, test a product that has variations and an "out of stock" status. Finally, clear the filter and make sure the product count returns to the original number for that language, not the combined total across all languages.

SearchWP and the search language scope

FacetWP can work with search, and some projects also use SearchWP alongside it. The official FacetWP Multilingual page specifically says that if SearchWP is used on a multilingual site with WPML or Polylang, you need to install the corresponding SearchWP integration extension for WPML or Polylang. Without it, the logic can drift apart: the facets and their counts may follow the active language, while the search results themselves return a broader set than intended.

The symptom can look like "FacetWP is wrong," but the real source is often the search layer. For example, a visitor enters an English query on a Russian page and sees posts from another language while the facet choices remain Russian. In that case, do not rush to change facetwp_query_args. First, verify which search engine is building the results, whether the required SearchWP language extension is installed, and whether the search result language matches the page language.

Parent term in a multilingual taxonomy

The Parent term setting is useful when you want to show only child terms of one parent, for example not all cities but only cities inside a selected country, or not all course categories but only the subcategories inside "Design." On a single-language site, this is usually simple: you choose the parent term ID, and the facet shows its descendants.

On a multilingual site, the translated parent term has a different ID. That means the same Parent term cannot automatically be correct for every language. FacetWP suggests three approaches: create separate facets for different languages and assign the correct parent ID, move the needed terms into a separate taxonomy, or use the documented facetwp_index_row hook to index children of multiple parent IDs. The last option is technical and requires re-indexing after the code changes.

The right choice depends on how the project is supported. If the site is maintained by an editor without a developer, separate language-specific facets are often easier to understand, even though they require discipline. If the site is evolving as a custom catalog, a dedicated taxonomy may be architecturally cleaner. A hook makes sense when the structure is already stable, there are only a few languages, and a developer is available to maintain the code after updates.

A safe rollback and testing workflow for a live site

Multilingual filtering affects content, the database, the FacetWP index, URLs, AJAX, and cache. Because of that, even a simple setting change can look like a major outage if it is made directly on a live page. A good practice is to have a small rollback path for every change.

What to record before making changes

Before enabling FacetWP Multilingual or running a large re-index, document the current structure: which languages are active, which catalog pages open correctly, which facets appear on the page, what the facet technical names are, which listing type is used, whether page caching is enabled, and whether AJAX has a separate configuration. This is not bureaucracy. When one facet disappears after a change, that record makes it much easier to see exactly what changed.

For a WPML project, record the translation modes for the relevant post types, taxonomies, and custom fields. For Polylang, record the list of languages, codes, URL mode, shared slug status, and whether a language was assigned to older content. For FacetWP, export the settings through the built-in Import / Export feature if it is available in your license and version. A database backup is mandatory before WPML troubleshooting, purging the index table, or assigning languages in bulk.

Minimum test set

Create a small test group of posts. For example, two posts per language, two translated categories, one custom field, and one search query. This set should not be hidden in drafts and should not depend on random imports. Its purpose is to show quickly whether the core chain works: language - data source - index - facet - result.

After each change, walk through the same sequence:

1. Open the default-language page with no facets selected.
2. Select one category or one field value.
3. Verify that the URL received a FacetWP parameter and did not lose its language segment.
4. Open the translated page and repeat the same selection using the translated value.
5. Clear the selection, refresh the page, and confirm that the original result count returns.

If something breaks, roll back the last change, not the whole project. If you disabled shared slugs, restore only that setting. If you added a hook, disable only that hook. If you changed a field translation preference, restore the original value and recheck the existing translations. This step-by-step approach saves far more time than trying to "fix everything" at once.

What not to do on production

Do not change the Polylang or WPML URL mode, fallback mode, taxonomy structure, and FacetWP hook code in a single pass. Do not clear the index table unless you know you will be able to run Re-index again successfully. Do not add snippets from a forum if they do not match your symptom and are not based on official hooks. Do not edit the main files of FacetWP, WPML, Polylang, or the theme. Those changes will disappear after updates and make troubleshooting harder.

If the site receives meaningful traffic and filtering matters for leads or sales, test everything on a staging copy first. After deploying to the live site, enable changes during off-peak hours, clear the cache, and test at least one page for each language. For a large catalog, think in advance about how long re-indexing will take, and do not start it a minute before an ad campaign or a bulk import.

Editorial setup checklist after installation

Once the add-on is enabled technically, it helps to review the page from an editor's perspective, not only a developer's. A multilingual filter should make sense to visitors: labels in their language, choices without duplicates, empty states that do not feel alarming, and reset and sorting behavior that feels predictable. If the interface looks like a mix of languages, users will not care that the AJAX request technically succeeded.

Labels and empty states

Check every visible string: the facet heading, search placeholder, reset button text, the "no results" message, sort and pager labels, and the mobile flyout text if you use it. Some of these strings may be translated through WPML String Translation or Polylang string translations, while others may require facetwp_i18n. The key is to keep the source strings in the default language and translate them consistently.

Pay special attention to the "no results" state. FacetWP tries to show relevant choices, but empty combinations can still happen: the filter is too narrow, translations are incomplete, products are hidden, or conditions are incompatible. The message should explain that the user can clear filters or change the selection, not make the page look broken. If the text comes from the theme or the page builder, translate it in the same place where it was created.

Choice order across languages

The order of values inside a facet can differ between languages. For example, Russian categories may sort by Cyrillic order, while English ones sort alphabetically in Latin script. That is normal if the order makes sense to the user. What is not normal is one language sorting by the original slug, another by the display value, and a third showing technical codes. In that case, check the facet orderby settings and the data source.

For manual term reordering, use the standard WordPress, WPML, Polylang, or compatible plugin tools. FacetWP has documentation for taxonomy ordering plugins and notes on specific conflicts. It is usually not worth writing a custom sorting hook for a minor editorial preference if the problem can be solved in the term structure itself.

Quality control after translating a new batch of content

When editors add new translations, filtering should remain predictable. Give them a short workflow: assign the language, connect the translation to the source post, choose the translated terms, fill in the fields, save the post, and check the public page. If the post does not appear in the facet after publishing, the editor should know whether to wait for automatic indexing or notify an administrator to run a manual Re-index.

On large sites, it is useful to maintain "control pages" for each language. These are ordinary catalog pages with one popular filter selected and an approximately known result count. After an import or update, the editor opens those pages and can immediately see whether an entire language, category, or post type has disappeared.

Common FacetWP Multilingual issues and how to diagnose them

Multilingual filtering problems often look the same on the surface: an empty list, the wrong terms, a missing facet, or a language that "jumps" during an AJAX refresh. But the causes are different. Below is a diagnostic map that helps you move from symptom to verification instead of changing everything at once.

After selecting a facet, the results become empty

Symptom: the page shows posts before filtering, but after selecting any value the result list becomes empty.

Likely cause: the posts in the listing do not have a language assigned, the translation was never created, the Polylang wizard was skipped, WPML is showing fallback posts, or FacetWP expects posts in the active language. Another possible cause is that FacetWP is filtering the wrong query or the page contains several active listings.

What to check: post language assignment, term translations, the presence of only one facetwp-template container, the Post Types Translation and Taxonomies Translations settings in WPML, the language settings in Polylang, and whether Re-index completed successfully.

How to fix it: assign a language to older content, create translations or duplicates, disable fallback for the FacetWP post types and taxonomies, keep only one FacetWP-enabled listing, re-index, and repeat the test in a clean browser window.

The facet shows duplicate categories in different languages

Symptom: on a Russian page, both "Design" and its Russian translation appear side by side, and the counts look off.

Likely cause: WPML fallback pulled default-language posts into translated results, terms were not translated, posts are linked to the source-language terms, or the facet uses a custom field whose values were not localized.

What to check: term translations, post-to-term relationships in each language, custom field rules, the "only show translated items" mode in WPML, and the absence of shared slugs in Polylang Pro for the affected objects.

How to fix it: translate the terms, update post relationships, align field values with the chosen translation model, save the facets, and run Re-index.

Polylang Pro shared slugs break the facets

Symptom: on a non-default language page, facets do not return the expected options, archives behave like regular pages, or the filter cannot tell which query it should process.

Likely cause: Polylang Pro is configured to use the same slug across translations. FacetWP officially states that this feature does not currently work correctly with it.

What to check: archive pages, translated slugs, the URL settings in Polylang, and whether different languages share the same pagename.

How to fix it: use unique slugs for translations, prepare redirects if needed, clear the cache, re-index FacetWP, and test the language-specific pages again.

WPML shows the wrong language after an AJAX refresh

Symptom: posts and facets sometimes switch to the admin language or look unstable when tested by a logged-in user.

Likely cause: the WPML language context from the admin area and the front end is getting mixed in the same browser. FacetWP documents this case and provides a hook that switches WPML to the language passed in FacetWP parameters.

What to check: whether the issue reproduces in incognito mode while logged out of the admin area, whether translations are correct, whether fallback is enabled, and whether the symptom matches the FacetWP documentation.

How to fix it: first confirm the issue outside the cache and without an admin session. If the symptom remains specifically WPML language-related, add the official snippet through a child theme, the Custom Hooks add-on, or a snippet plugin, and then test only the affected page.

The indexer hangs or says the index table is empty

Symptom: Re-index does not finish, stalls at one percentage, or shows a message saying the index table is empty.

Likely cause: insufficient memory, blocked internal HTTP requests, hosting conflicts, a problematic post or term, the Multilingual add-on missing while WPML or Polylang is active, or a damaged index table.

What to check: the error log, WP_DEBUG_LOG, memory limits, whether the Multilingual add-on is installed, whether posts have languages assigned, whether another Re-index attempt is possible, and whether the index table needs to be purged.

How to fix it: run Re-index again and, if needed, clear the index table using the built-in FacetWP button and then re-index. If there are signs of memory exhaustion, raise the limit within the server's capabilities. If the site is protected with HTTP Basic Authentication, follow the official FacetWP instructions for the indexer's internal requests. Any database-level action should be done only after a backup.

When FacetWP Multilingual is the right choice

FacetWP Multilingual is worth using when the site already relies on FacetWP, multilingual support is built with WPML or Polylang, and the filters need to show results strictly in the active language. It is a strong solution for catalogs and knowledge bases where fast AJAX facets, clean URL parameters, translatable labels, and a manageable index all matter.

Before launching it on a live site, verify three things: posts have a language assigned, the sources of the choices are either translated or synchronized according to a clear logic, and the FacetWP listing works correctly in every language version before and after a facet is selected. If those conditions are met, the add-on usually provides a predictable connection between FacetWP and WPML or Polylang.

If you are ready to test the setup on a copy of the site, start with one listing and two facets. After a successful test, you can expand the scenario: add search, sorting, pagination, custom fields, ACF, and extra languages. Once the basic validation is complete, you can download the FacetWP Multilingual archive and move on to implementing it on your catalog page.

The main selection criterion is simple: if the site needs to filter translated content without mixing languages, and the core filtering is already built on FacetWP, this add-on covers exactly the layer that most often breaks between the translation plugin and faceted search.