Polylang Pro - WordPress Plugin

A Practical Guide to Setting Up and Using Polylang Pro on a WordPress Site

Polylang Pro is not just there to add flags to a menu. In real-world use, it becomes your site's language management layer: it links translated pages together, helps you choose a URL structure, gives editors language-level permissions, supports the block editor, and lets you build translation into your normal WordPress publishing workflow.

In this guide, we'll look at how to prepare your site, what to verify after installation, which settings to enable right away, where not to rush, how to translate a page, menu, theme strings, media, and SEO-friendly URLs, and how to diagnose common issues. This walkthrough is for site owners, editors, webmasters, and agencies already working with WordPress who want to build a manageable multilingual site without turning content into a mess.

One important point up front: Polylang Pro is not a "translate the entire site in one click" button. Even if you use machine translation through DeepL, every piece of content still needs to be reviewed, linked to its original, published intentionally, and checked on the live site. That is why this guide is not a promotional overview, but a practical set of instructions with verification steps and safe implementation advice.

When this plugin genuinely helps, and when it makes the project harder

Polylang Pro works best on sites where translations need to stay inside WordPress rather than being pushed into a separate external system. That includes corporate sites, blogs, portfolios, media sites, service websites, catalogs, educational projects, and content sections of ecommerce stores. Users get separate versions of pages and posts, while WordPress understands which content belongs to which language.

The plugin is especially useful if you need separate URLs for language versions, translated categories and tags, theme string management, a language switcher in menus or blocks, support for the block editor, support for template parts in Site Editor, and the ability to export content to a translator via XLIFF. For team-based projects, it also matters that current Polylang Pro releases include language capabilities for roles: you can restrict which languages are available to a specific editor or translator.

There are scenarios where it may not be the best choice. If you need fully automated translation for the entire site without manual review, it makes sense to compare it in advance with services built around automation. If the site runs on WooCommerce, Polylang Pro alone is not enough for a fully multilingual store: products, cart, checkout, emails, and store-specific elements require Polylang for WooCommerce. If the site is built with a complex visual builder, check the limitations carefully: the official documentation explicitly warns that Polylang Pro's DeepL integration does not support content created with some builders, including Elementor and Divi, and also does not work with Site Editor content for machine translation.

Finally, Polylang Pro requires discipline. You need to decide which languages to launch, which pages to translate first, who owns translation quality, where the switcher will appear, which URLs stay unchanged, and which ones should be localized. Without that map, even a good plugin turns into a collection of disconnected language copies.

What to check before installing it on a production site

Before installing a multilingual plugin, it is worth pausing for a minute. Polylang Pro does not change your site's design - it changes the structure of content and navigation. Mistakes at that level usually do not show up immediately: some pages disappear from the front end, menus point to old URLs, translated categories are no longer linked to the originals, and search engines see an incomplete language structure.

Compatibility, backup, and rollout order

For the current version of Polylang Pro, the developer lists minimum WordPress and PHP requirements in the changelog. Before installing it, make sure the site is not running on an outdated environment and that the theme and core plugins are up to date. On a live site, the safer approach is to repeat the installation on a staging copy first, where you can test the URL structure, language switcher, menus, template parts, and media translation without risking the visitor experience.

If another multilingual plugin was used before, do not run multiple solutions like that at the same time. WordPress.org explicitly warns that other multilingual plugins should be deactivated before enabling Polylang, otherwise you may get unpredictable results. Migrating from the free version of Polylang to Polylang Pro is simpler: both versions use shared data, and activating Pro automatically deactivates the free version.

Your language and URL map

Put together a short table before rollout. It should include the language, WordPress locale, language code, text direction, planned URL structure, responsible editor, and translation status. This helps you avoid mixing, for example, Spanish for Spain with Latin American Spanish, assigning the same code to different languages, or changing URLs after indexing has already started.

The short version is simple: before installation, you need to understand not just the list of languages, but the workflow. If the site already has a large content base, add a separate step for assigning languages to existing content. If the site is new, start with two languages and complete one full workflow end to end: page, menu, theme string, switcher, and front-end verification.

Installation and first launch without version confusion

With Polylang Pro, installation differs from the free plugin because the ZIP file is uploaded manually through the admin panel. In WordPress, the standard path is Plugins - Add New - Upload Plugin. After selecting the polylang-pro.zip archive, activate the plugin. This guide does not cover purchasing, payment, or obtaining commercial access - it assumes the installation archive is already available to the administrator.

On first activation, the setup wizard starts automatically. If you skipped it, the official documentation points to Languages - Setup. The wizard is not just cosmetic: it helps you create languages, choose media behavior, assign a language to existing content, and, if a static homepage is set, create linked language versions of that homepage.

What to do in the setup wizard

Do not click through the wizard mechanically. At every step, make a decision that will not be easy to change later without consequences.

1. Add the site's primary language and one additional language that you will launch first. The first language you add becomes the default language.
2. At the media step, enable media translation only if you need to translate file titles, captions, alt text, and descriptions. The file itself is not duplicated when media translation is enabled.
3. If the site already contains content, assign it to the primary language. Otherwise, part of the content may not appear on the front end.
4. If you use a static homepage, check whether linked pages were created for the other languages. In the Pro version, the existing homepage can be duplicated with the same content, but the text still needs to be translated.
5. After the final step, do not treat the job as finished yet: you still need to configure the menu and the language switcher separately.

Initial verification after activation

Right after installation, open Languages - Languages. The table should show the languages, their locales, codes, order, and which one is set as the default. Then open several pages in the WordPress admin and make sure a language panel has appeared. On the front end, check the homepage and one internal page: the URL should match the selected structure instead of leading to old, unassigned content.

Result check: if some pages disappear after you enable the plugin, first verify whether a language has been assigned to them. On an existing site, that is a common reason content seems to "vanish."

Configuring languages, locales, and URL structure

The Languages - Languages section does more than manage language names. It defines settings that affect URLs, loading WordPress language files, displaying flags, the order in the switcher, and the behavior of some language features. A mistake here can lead to 404 errors, incorrect theme interface translations, or awkward navigation.

Locale and language code

The locale tells WordPress which translation files to load for core, the theme, and plugins. The language code is used in URLs and language detection. For common languages, Polylang fills in the standard values automatically, but custom languages need to be configured carefully. If the locale does not match the actual WordPress language pack, the theme or plugin interface may remain in the original language.

Changing the language code after launch is risky because it may be part of the URL. If you had a URL like /fr/guide/ and then changed the code, old links may stop working unless you add redirects. That is why language codes should be finalized before large-scale translation and indexing begin.

Subdirectories, subdomains, or separate domains

Polylang Pro supports different language URL formats: language codes in the path, subdomains, or separate domains. For most content-driven sites, the clearest option is subdirectories such as /en/ and /fr/. Subdomains and separate domains make more sense when the project serves different markets, analytics setups, marketing teams, or regional domain strategies.

When choosing a URL structure, think about caching, sitemaps, canonical URLs, redirects, analytics, and inbound links. Once the site is live, changing the scheme without a migration plan is a bad idea. In its guide to multilingual WordPress, Kinsta specifically highlights URL structure as a major SEO decision, and notes that translating URLs, metadata, menus, and other content matters just as much as translating the page copy itself.

Translating slugs and service parts of the URL

One Pro feature is slug translation for categories, tags, post types, taxonomies, and other parts of the URL. For example, the system fragment category can be translated so that the French URL looks like /fr/categorie/voyage/, while the English one looks like /en/category/travel/. The setting lives under Languages - Translations, where you can filter strings by the URL slugs group.

Do not translate URLs just for appearance. First decide which pages and taxonomies will actually be promoted in search, which URLs are already indexed, which characters are safe for the target language, and which redirects will be required. For languages with complex character sets, it is sometimes more practical to keep Latin characters or use a clear transliteration.

Translating content: manual mode, duplication, and synchronization

The main working area in Polylang Pro is not a separate external dashboard, but the familiar WordPress editor. A post or page gets a language panel that shows the relationship between the original and its translations. From there, you can create a translation, enable content duplication, or turn on synchronization if the task calls for the same material across several regional versions.

Manual translation as the main quality control layer

Manual translation is the right fit for service pages, landing pages, legal content, instructions, terminology-heavy material, and any content where tone matters. Create the translation from the language panel, then fill in the title, body content, excerpt, SEO fields, categories, tags, and related content. If you use an SEO plugin, verify that the metadata was translated in the language version itself rather than left as a copy of the original.

After publishing, open the page while logged out and verify that the language switcher points to the translated counterpart rather than the homepage in another language. By default, the switcher links to translations of the current page; if the current page has no translation, it may point to the homepage of the corresponding language instead.

Content duplication

The duplication feature in Polylang Pro copies the title, content, media, galleries, and excerpt when you create a translation. That is useful when the page structure is already built: the editor does not need to rebuild blocks, galleries, or the section order from scratch. But duplication is not translation. After creating the language version, you still need to review the text, alt text, captions, buttons, forms, and internal links.

The documentation points out an important detail: other data types, such as taxonomies, the featured image, some metadata, page order, and the template, may be copied regardless of whether duplication is enabled. So do not check only the visible text - review the supporting fields as well, especially on pages that use custom post types.

Synchronized entries for regional variants

Synchronization is useful when the same material needs to stay aligned across several language or regional versions. For example, an English page for the UK and the US may differ in categories or media captions, but the main body text should update at the same time. Polylang Pro lets you enable synchronization in the language panel, so saving the source entry will propagate changes to linked versions.

Use this feature carefully. For independent translations, it can cause problems: an editor changes the original, and the update overwrites part of the translated content. A good rule is to enable synchronization only where the team has already agreed which elements must stay identical and which ones can vary by language.

Language switcher, menus, and block themes

The language switcher is the visible part of the entire system. If it is placed poorly or points to the wrong destination, users will not notice how carefully you configured URLs and languages behind the scenes. Polylang supports several output methods: a menu item, a block, a widget, a Site Editor navigation block, and a PHP template tag for developers.

Classic menus and widgets

In classic themes, the switcher can be added to a menu. If the language box is not visible in the menu editor, check Screen Options: the metabox may be hidden. In the switcher settings, you can control whether language names, flags, the current language, a dropdown, and language order are displayed.

Be careful with flags. A flag represents a country, while a language may be used across multiple countries. For a site in English, French, and German, that is often acceptable. For regional languages or an international audience, text labels are often clearer and safer.

Block Editor, Widgets, and Site Editor

Polylang Pro adds the language switcher as a block for the newer widget editor, Site Editor, and the navigation block. That matters for modern block themes, where menus and template parts are edited through Appearance - Editor. In Site Editor, you can translate pages, navigation, template parts, and reusable blocks, but there is an important limitation: the plugin does not translate templates as standalone entities. If no translation exists for a template part, the original version may still be used for other languages.

A practical verification step is to open the homepage, one internal page, a category archive, and a page with no translation after adding the switcher. On each one, check which languages are visible, where the links go, and whether the switcher appears empty. The official documentation explains that if a language has no published content, the switcher may hide that language on the front end so it does not send visitors to a 404 page.

Small CSS tweak for the visual appearance

If your theme outputs Polylang elements with the lang-item and current-lang classes, you can gently improve switcher alignment in the menu with CSS. Add the code under Appearance - Customize - Additional CSS or in a child theme. Before using it, inspect the classes in the browser because your theme may alter the menu markup.

/* Compact language switcher in the WordPress menu */
.main-navigation .lang-item > a,
.wp-block-navigation .lang-item > a {
  display: inline-flex;
  align-items: center;
  gap: 0.35rem;
  padding-inline: 0.55rem;
  border-radius: 999px;
}

.main-navigation .current-lang > a,
.wp-block-navigation .current-lang > a {
  background: rgba(34, 113, 177, 0.12);
  font-weight: 600;
}

After inserting it, reload the page without cache and check the desktop menu, mobile menu, and keyboard navigation. If the styles break the theme, remove the CSS block or narrow the selectors to a specific menu container.

Theme strings, media, and the items people often forget to translate

A multilingual site does not break only at the page level. Teams often translate the main content but forget the site tagline, widget headings, theme button labels, image alt text, footer copy, and category slugs. As a result, users see a page in one language while interface details remain in another.

Interface strings and theme settings

The Languages - Translations section is used for strings that are not regular pages or posts. That includes the site name, description, widget titles, and some theme and plugin settings. The documentation clarifies that at least one language must be added before this table becomes available. The table shows the source string and translation fields for each language; after filling them in, click Save Changes.

In practice, it helps to keep a separate checklist of strings: header, footer, forms, buttons, card labels, subscription messages, widgets, and error pages. After translating them, clear the cache and verify the site in a private window. If a string does not appear in the table, the theme or plugin may not have registered it as translatable for Polylang.

Media: when to enable the module

Media translation is disabled by default. That is a reasonable choice: most sites do not need a language entry for every file. Polylang does not copy the file itself when translating media - it translates the associated text fields: title, alt text, caption, and description. Enable the module if those fields matter for SEO, accessibility, or local context.

If an image contains text inside the image itself, media translation will not solve that problem. In that case, you need separate files for different languages. The documentation explicitly states that Polylang does not create a relationship between two different media files for this scenario. So for banners, infographics, and images with embedded text, plan separate assets and verify where each one is used.

DeepL, XLIFF, and working with translators

Polylang Pro supports two different ways to speed up translation: machine translation through DeepL and XLIFF export/import for a professional translation workflow. These features do not compete with each other - they solve different problems. DeepL is useful for producing a first draft that a human then edits. XLIFF is helpful when translation is handled by an external specialist in a CAT tool and you need to preserve WordPress content relationships.

What the DeepL integration actually does

DeepL is built into the Polylang Pro interface: you can launch translation from the editor for a specific post or page, from string translations, for taxonomies, and for some fields if the configuration supports it. But the documentation also highlights its limitations. Machine translation does not translate the entire site with one click, works item by item, and does not automatically update an existing language version after the original changes.

That means after machine translation, you still need to open the generated draft and check terminology, links, buttons, headings, SEO fields, and images. If the original changes, do not rely on automatic translation updates. In some cases, it is better to manually add a new paragraph to the language version than to regenerate the entire piece and spend more quota.

XLIFF for a professional workflow

XLIFF exports translatable content while preserving structure, identifiers, and language relationships. The official documentation warns that XLIFF is not meant to be edited manually like a spreadsheet - it should be opened in a CAT tool. The file can only be imported back into the same site that generated it, because it contains references to the original data.

A practical workflow looks like this: the editor selects pages under Pages - All Pages, applies the bulk action Translate, chooses the target language, and exports XLIFF. The translator works in a CAT tool and then returns the XLIFF file. After import, Polylang Pro inserts the translations into the correct fields and keeps them linked to the originals. This is especially useful on large sites, where you cannot just send a translator a copy of raw HTML and hope they do not break the block structure.

ACF Pro, custom fields, and complex pages

If the site uses ACF Pro, custom post types, repeaters, flexible sections, or blocks, configuring Polylang Pro becomes much more project-specific. You cannot simply enable translation for every field and expect a correct result. You need to decide which fields are translated, which are copied once, which are synchronized, and which should remain empty when a translation is created.

The ACF documentation points out that under the newer logic, the field group itself is no longer translated as a separate object. Instead, language-specific differences can be handled with display rules by language, while field labels and instructions can be translated through the strings table. Each field supports different behaviors: Ignore, Copy Once, Translate, Translate Once, and Synchronize.

How to choose the right field behavior

Text fields, headings, descriptions, button URLs, and WYSIWYG blocks are usually translated. Images, post relationships, taxonomies, and files are often better copied once, so the editor gets the original structure and can then review local values manually. Synchronization is useful for technical numbers, flags, shared settings, and relationships that truly need to remain identical.

The most dangerous mistake is synchronizing a field that an editor later translates manually. The next time the original is updated, the translated value may be overwritten or pushed back into a shared structure. For complex repeaters and flexible sections, it is worth testing one page on a staging site first and then documenting the rules for editors.

Verifying the ACF scenario

1. Create a test page with the same set of ACF fields as the live page.
2. Assign a language and create a translation through the language panel.
3. Check which fields were copied, which stayed empty, and which require manual translation.
4. Update the original and save it so you can see which values changed in the translation.
5. Document the rules in the editor guide: what can be changed and what stays synchronized.

Practical example: translating a service page, updating the menu, and verifying the SEO URL

Let's walk through a scenario that comes up often on a corporate site: there is a service page in the site's primary language, and you need to prepare an English version, add it to the menu, translate a footer button string, create a clear URL, and verify that users see the correct language version.

Goal and preparation

The goal is to get a linked English version of a service page that is reachable through the menu and the language switcher. Before you begin, the primary language and English should already be added, the URL type selected, the source page published, at least one language switcher configured, and the cache for the test page cleared.

Steps in the admin panel

1. Open the original service page in the WordPress editor and make sure it has the primary language assigned.
2. In the language panel, click the icon to create the English translation.
3. If the page structure is complex, enable duplication before creating the translation so the blocks, gallery, and section order are carried over.
4. Translate the title, main text, buttons, SEO title, meta description, image alt text, and internal links.
5. Open Languages - Translations and translate the footer button string if it is output by the theme or widget.
6. Check the page slug. If you need a localized URL, configure URL translation or set the slug manually on the language version.
7. Add the English page to the appropriate menu or translate the navigation through Site Editor if you are using a block theme.
8. Publish the translation and open it in a private window.

Result verification

On the front end, five signals should line up: the URL belongs to the English version, the content is translated, the menu leads to English pages, the switcher returns to the source-language counterpart, and the footer string appears in English. If the switcher points to the homepage, the current page is either not linked to a translation or the translation is not published.

Important detail: if you change the original after publishing, the translation does not become current automatically. Add an editorial rule: every important change to the source content should create a task to update the language versions.

Verifying the result on the site and in search-related behavior

After configuration, it is not enough to inspect the admin area. Polylang Pro may be set up correctly inside WordPress, while users still see issues because of cache, theme behavior, an untranslated menu, missing published content, or old redirects. Verification should move from the public page back to the underlying setting.

What to open manually

• The homepage of each language, to verify the URL, menu, and switcher.
• A translated service page or post, to make sure language versions are correctly linked.
• A category archive and tag page, if taxonomies are part of navigation or SEO.
• A page with a form, widgets, or a footer, to catch untranslated theme and plugin strings.
• A page with no translation, to see how the switcher behaves and whether it leads to a 404.

What to verify technically

Inspect the page source or use SEO tools to verify that language versions are connected through hreflang, that the canonical URL does not point to a different language page, and that the SEO plugin outputs localized metadata. Polylang Pro advertises automatic handling for hreflang and Open Graph tags, but the final page still depends on the theme, the SEO plugin, caching, and correct translation relationships.

If caching is enabled, clear the site cache, CDN cache, and object cache after large changes to languages, menus, or URLs. Some issues look like Polylang errors when the real problem is that visitors are still seeing an older menu or outdated links.

Common Polylang Pro issues and how to diagnose them

Most errors are not caused by a single failure, but by misalignment: no language assigned, translation not published, URL changed without a redirect, menu not translated, cache serving an old version, and an editor expecting automatic updates where none exist. Below are the typical symptoms and the order in which to check them.

The language switcher does not appear

Symptom: the block or menu item has been added, but there is no switcher on the front end.

Causes: the language has no published content, the current page has no translation, the menu metabox is hidden, the block was inserted into a template part that this page does not use, or the cache is showing outdated markup.

What to check: open the pages table and confirm there is published content for each language, then check the specific page and its language relationship. In a block theme, open Appearance - Editor and make sure the switcher is placed in the correct navigation or template part.

How to fix it: publish at least one page in the target language, link the translation to the original, add the switcher to the correct menu, and clear the cache. If the language is still in preparation, use Polylang Pro's language deactivation option so editors can keep working while visitors do not see an unfinished version.

Some pages disappeared from the front end after activation

Symptom: the pages still exist in the admin area, but visitors do not see them in the expected language, or archives have become empty.

Causes: existing content was never assigned a language, taxonomies are not linked, menus point to old pages, and front-end filtering shows only content for the current language.

What to check: assign a language to several affected pages, open categories and tags, and review the menu. If the site already had content before installation, return to the wizard step or use the actions for assigning a language to existing content.

How to fix it: assign the primary language to your current content, then create translations gradually. Do not delete a language or change its code until you understand how that will affect the URLs.

DeepL translated the page, but changes from the original did not reach the translation

Symptom: the editor updated the source page, but the language version still shows the older text.

Causes: the DeepL integration is not continuous synchronization. The documentation explicitly states that a translated version is not updated automatically when the original changes.

What to check: compare the modification dates of the original and the translation, see which section changed, check the quota, and decide whether a full machine retranslation is really needed.

How to fix it: for small edits, update the translation manually. For larger changes, you can recreate the translation, but first evaluate whether that will overwrite sections that were already refined by a human editor.

A URL in another language returns a 404 or goes to the wrong place

Symptom: the translated page is published, but its language URL is unavailable, or the switcher leads to an unexpected URL.

Causes: the language code was changed, permalinks were not refreshed, the slug was translated in the wrong string group, older redirects conflict with the new structure, or the route cache was not cleared.

What to check: open Settings - Permalinks and save the structure without changing it, verify the slug translation under Languages - Translations, then temporarily disable conflicting redirects on a staging site.

How to fix it: restore the correct language code, resave permalinks, set up redirects from the old URLs, and do not change the URL structure without a migration map.

ACF fields are overwritten or not translated

Symptom: after saving the original, the translated page loses local text, a repeater changes structure, or a field stays empty.

Causes: the wrong field behavior was selected: synchronization instead of translation, copying instead of manual entry, or ignoring a field that should contain text.

What to check: open the ACF field group settings, the translations tab, and the behavior for the specific field. Test one sample page before applying the setup in bulk.

How to fix it: for text fields, use translation or translate once; for relationships and media, copy once is usually the safer choice; leave synchronization for values that truly need to stay identical.

The WooCommerce store is only partially translated

Symptom: store pages, cart, checkout, emails, or products do not behave like regular posts.

Causes: Polylang or Polylang Pro by themselves are not a complete multilingual solution for WooCommerce.

What to check: verify whether Polylang for WooCommerce is installed, and whether system store pages, attributes, categories, emails, and checkout elements have been translated.

How to fix it: for a store, use the official WooCommerce add-on and test a full order flow in each language. If the store is business-critical, do not launch a language version without a separate cart and email test.

Safe improvements for the editorial workflow

For Polylang Pro, the most important improvements are usually not in code, but in editorial discipline. Define who creates the translation, who reviews terminology, who publishes, who owns the URL, and who tests the public-facing result. That lowers the risk of accidentally publishing a draft language or overwriting a translation that was edited manually.

A minimal operating policy for the team

• A new language should first be created as a working language and, if needed, temporarily deactivated for visitors.
• Every important page should have a responsible editor and a status: draft, in translation, under review, published.
• Before publishing, verify menus, theme strings, SEO URLs, metadata, images, and internal links.
• After the original changes, create a task to review translations, because machine-generated and manually edited versions do not update themselves.
• For ACF-driven pages, document field behavior rules in a separate editor guide.

If several translators are involved, consider using Polylang Pro's language capabilities. According to the documentation, they let you limit access to languages, translation strings, language management, and machine translation. Roll this out carefully through roles: start with a test user, then expand it to the editorial group.

When Polylang Pro is the right choice

Polylang Pro is worth using if you need a manageable multilingual WordPress site where translations stay linked to the original, URLs can be configured for SEO, the language switcher is built into menus or Site Editor, and editors work inside the familiar admin panel. It is especially strong where control matters: human editing after machine translation, XLIFF for translators, rules for ACF fields, language roles, and careful staged publishing.

Do not expect the plugin to define your editorial strategy for you. Good results come when you have a language map before installation, complete the initial verification after installation, and test menus, strings, URLs, SEO fields, media, and public pages before publishing. If that approach fits your workflow, you can download Polylang Pro and test it on a staging copy of the site first.

Final recommendation: do not start with every language at once. Start with one complete path. Translate one important page, one menu, one interface string, the media fields, and the URL, then check the result as a visitor would. If that path works, scaling to the rest of the site will be much smoother.