The SEO Framework is compatible with Polylang, WPML, TranslatePress, and MultilingualPress out of the box. Other translation plugins are also compatible, but some features like per-language sitemaps and improved sitemap flushing support are missing.
Multisite translation plugins (MultilingualPress)
MultilingualPress is special. Instead of running all languages on one single WordPress website, it works via a WordPress multisite network utilizing a unique site for each language. This is unique and why we highlight it separately from the other plugins.
Its integration is much how Automattic deals with internationalization on WordPress.com and WordPress.org as well — and it is, in our opinion, the only correct method. However, we understand that this solution is not feasible for everyone and that running a multisite can be steeply costly for many.
Issue #1: Site language settings
Ensure that you set the site language (at the General Options of your WordPress site) to the visitor’s language of the website. This setting makes sure The SEO Framework recognizes the language of the site for meta-tag generation, and our dictionary API services brought with Focus.
You can change the display language of the admin interface for each user individually on their profile page. To use a different language, you must install it first.
Same-site translation plugins (WPML, Polylang, et al.)
Most other translation plugins work on the same site. We’ll cover WPML and Polylang in extent due to their sheer popularity.
These plugins allow you to set a language on a per-post and per-term (category, tag) basis, which means that the plugins need to make integrity changes to WordPress on each request, which makes integration a bit harder for us.
Although most translation plugins have a different foundation, their goal is homogenous. As such, these issues are typical across the board.
Open Graph locale: TSF derives the Open Graph locale from the site language WordPress reports for the current page. When Facebook doesn’t support that locale, TSF falls back to a supported locale of the same language, or to en_US.
Issue #1a: Homepage settings (homepage shows latest posts)
All options set on the global SEO Settings page for the homepage will affect all languages. So, if you put a custom title for the homepage there, all configured languages will have their title changed.
Therefore, we advise against filling in the homepage settings when using a same-site translation plugin. When using WPML or Polylang, we urge you not to set the homepage as a blog. Instead, we recommend setting the homepage as a static page.
Still, for WPML, you can workaround this via their String Translations tool. We explained how to use this below.
Issue #1b: Homepage settings (homepage is a static page)
When your homepage is a static page, we recommend only adjusting the homepage settings via the page-edit screen, and not via the general SEO settings screen. This way, you can set custom titles and descriptions for each language.
Again, for WPML, you can workaround this via their String Translations tool. We explained how to use this below.
Issue #2: Custom post type (CPT) language support
For WPML and Polylang, custom post types must be configured as translatable first. Otherwise, their posts might get included twice in the sitemap. You can learn how to do that here:
Also, like with the homepage settings, Custom Post Type Archives meta settings will not be translatable.
But again, for WPML, you can workaround this via their String Translations tool. We explained how to use this below.
Issue #3: Focus synonym/inflection lookup support
The Focus extension only obtains the lexical information based on the site language, and not for the language of the post you are editing.
For WPML and Polylang, we are looking into resolving this newfound limitation since we understand it hampers our users significantly. However, we firmly believe that this is for them to resolve, especially since WordPress 4.7 brought extended support for user-based localization that makes patching these issues easy, without any intervention from other plugins necessary.
Same-site sitemaps support
The SEO Framework outputs a unique sitemap for each language when the optimized sitemap is enabled. It is the only correct way to deal with multilingual sites, without using awfully complex lingual markup. WordPress Core sitemaps do not get these per-language extras.
Find the advertised URLs at SEO Settings → Sitemap Settings, under “View translated sitemaps.” Each link uses the language name as its text. That list appears when the optimized sitemap is on and WPML or Polylang uses a subdirectory, parameter, or Polylang “from content” URL format. TranslatePress lists each published language that has a language directory.
Those sitemaps live at the site root. They are not placed under a static front-page slug. Depending on the translation URL format, they look like this:
example.com/sitemap.xml (default language)
example.com/es/sitemap.xml (subdirectory)
example.com/sitemap.xml?lang=es (query parameter)
es.example.com/sitemap.xml (subdomain)If Polylang does not remove /language/ from pretty permalinks, subdirectory sitemaps use that prefix: example.com/language/es/sitemap.xml.
Pretty permalinks are the supported setup. With plain permalinks, Polylang still serves extra language sitemaps. WPML extra sitemap URLs stay in the default language on plain permalinks.
Submit each sitemap to Google Search Console and Bing’s Webmaster Tools. They crawl those URLs periodically.
If you use WPML or Polylang with subdirectory, parameter, or Polylang “from content” URL formats, robots.txt lists /sitemap.xml and each extra language sitemap. A default-language directory URL such as /en/sitemap.xml can still resolve when that slug is shown. robots.txt does not list that alias.
Subdomain setups are different. Each host already has its own /sitemap.xml, so the main site’s robots.txt does not list the other hosts.
With TranslatePress, each published language that has a language directory gets its own sitemap at example.com/es/sitemap.xml. robots.txt lists every language sitemap except the one of the language served without a directory.
With other translation plugins, only the primary language’s sitemap is listed in robots.txt. We cannot guess those sitemap locations accurately.
Whenever you update any post with WPML or Polylang active, all sitemap caches are flushed. TSF clears the sitemap cache of every language, including when your site uses a persistent object cache. TranslatePress sitemap caches are cleared the same way.
WPML
WPML is a premium same-site translation plugin. It works by attaching its lingual metadata to each post individually, and it requests the correct version via a reverse URL lookup in the database.
Below, you find the issue most users face when using WPML in combination with TSF. Also, be sure to check out the “same-site issues” above.
Automatic translation: Since v5.2, WPML’s automatic translations of SEO titles and meta descriptions stay within recommended character limits.
Issue #1: Translation Editor support
You cannot adjust a page’s robots-meta or Extension Manager’s meta when using the WPML Translation Editor feature. We recommend disabling this feature for pages you want to have more control over editing.
Issue #2: Pages won’t index
WPML has a feature that redirects users based on the browser language. This feature affects search engine crawlers, preventing them from finding your translated pages. To fix this issue, go to “WP Admin → WPML → Languages → Browser language redirect,” and disable that. It may take time for search engines to notice changes.
This affects all sites using WPML; not only in combination with The SEO Framework. We recommend everyone to disable this feature.
String Translations tool
WPML has a feature called String Translations. This feature allows you to translate strings that are not directly translatable via the WordPress interface. You can find this feature at “WP Admin → WPML → String Translation”.
To translate The SEO Framework’s options, follow these steps:
- On the String Translation editor, scroll down, select “Translate texts in admin screens.”
- Search for “autodescription,” and select the Options you want to translate.
- Hit “Add to String Translation.”
- Return to “WPML → String Translation.”
- Now, you should see the selected option under Name (note: might be on the second page).
- Hit the big plus under the other languages to set a custom value.
- Click anywhere on the page to save your translation.
Polylang
Polylang works differently from WPML, since it augments (annihilates) the WordPress installation URL’s integrity, among changing the WordPress Query based on cookies–affecting your site’s performance by roughly 20%. Moreover, because of this, some theme and plugin functionality may stop working altogether after Polylang sets a cookie in your browser.
Luckily, Googlebot and Bingbot don’t reuse cookies, so they can freely crawl your site unhampered.
Nevertheless, many other issues stem from this URL and query augmentation, and to work around these, we must maintain its allow-and blocklists for an endless battle for compatibility. So, we don’t recommend using this plugin, even though it’s a free alternative to WPML.
Below, you find the issue most users face when using Polylang in combination with TSF. Also, be sure to check out the “same-site issues” above.
Exclusions: Since v5.2, posts you excluded from on-site search and archives no longer appear in translated search and archive results.
Issue #1: Sitemap is not visible
Since Polylang attaches a cookie to your browser once you interact with the language switcher, you won’t be able to visit the sitemaps of all other languages. Unfortunately, this can also affect search engines–where they’ll warn you that they see an HTML file instead of an actual sitemap.
To work around this, you should disable the “Detect browser language” setting in Polylang–you can find it at “WP Admin → Languages → Settings → Module”. With that feature disabled, search engines and your users are free to browse your website without buggy side effects. We assure you that search engines will show links to your website in the potential visitor’s preferred language.
If you wish to validate if the sitemap is reachable, try using a different browser, or go to your sitemap in incognito mode. When in doubt, use a legitimate third-party service to validate the sitemap, such as Google Search Console.
Issue #2: Translated sitemaps don’t work
If translated sitemaps always show the main language’s sitemap via, for example, /sitemap.xml?lang=es, then you should change the “URL modifications” setting in Polylang from “The language is set from content” to anything else (we recommend using subdomains, if possible) — you can find it at WP Admin → Languages → Settings → Module. This will change how Polylang writes the URLs, so this is best done on new setups only.