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.
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.
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. It is the only correct way to deal with multilingual sites, without using awfully complex 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)You can submit each sitemap to Google Search Console and Bing’s Webmaster Tools. And they will crawl it periodically.
But, if you use WPML or Polylang in subdirectory, from content, or parameter translation URL format, the sitemaps can be discovered automatically via robots.txt. With other translation plugins, only the primary language’s sitemap is listed in the robots.txt file because we can’t accurately guess the other sitemap’s locations.
Whenever you update any post with WPML or Polylang active, all sitemaps will have their caches flushed.
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.
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.
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 langauge’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.