The SEO Framework is compatible with Polylang, WPML, and MultilingualPress out of the box. Other translation plugins, such as TranslatePress, are also compatible, but some features like improved sitemap flushing support are missing.
MultilingualPress is special. It works via a WordPress Multisite network utilizing a unique site for each language, instead of running them all on one single website. So, that is 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. This system has only one caveat, and it is, in our opinion, the right way forward. However, we understand that this solution is not feasible for everyone and that running a multisite can be steeply costly for many.
The only caveat: 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 caveats are typical across the board.
Caveat #1a: Homepage settings (homepage shows latest posts)
All options set to the general 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 not setting the homepage as a blog at all. Instead, we recommend setting the homepage as a static page.
Caveat #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.
Caveat #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:
Caveat #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. It is the only correct way to deal with multilingual sites, without using awfully specific lingual markup. Depending on your configuration, you can find the other sitemaps by using the language code (for example,
es for Spanish), as shown in the block below.
example.com/es/sitemap.xml (subdirectory) example.com/sitemap.xml?lang=es (query) example.com/?lang=es/sitemap.xml (query, corner-case) es.example.com/sitemap.xml (subdomain)
Whenever you update any post with WPML or Polylang active, all sitemaps will have their caches flushed. However, only the primary language’s sitemap is pinged to the search engine—but, when the search engines are aware of the other sitemaps, they will crawl them autonomously anyway.
Lastly, only the primary language’s sitemap is listed in the robots.txt file, because we can’t accurately guess the other sitemap’s locations.
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 caveat most users have to face when using WPML in combination with TSF. Also, be sure to check out the “same-site caveats” above.
Caveat #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.
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.
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 caveat most users have to face when using Polylang in combination with TSF. Also, be sure to check out the “same-site caveats” above.
Caveat #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 can 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.