SEO

PerfLocale ships a full modern-SEO stack designed specifically for multilingual sites. Hreflang and sitemaps are on by default; the other features are opt-in and disabled out of the box to keep the plugin lightweight. Configure all of it at Settings → SEO.

Hreflang alternates

Every frontend page automatically emits <link rel="alternate" hreflang="..."> tags for every translation that exists, plus hreflang="x-default" pointing at the default-language version. Generated from the translation group, cached per-request, and deduplicated when an SEO plugin (Yoast, Rank Math, AIOSEO, SEOPress, Slim SEO, The SEO Framework) is active so there are never two sets of hreflang tags fighting. Nothing to configure.

Tag values use canonical BCP 47 form — lowercase language + UPPERCASE region (en-US, en-GB, de-DE, pt-BR). The HTML5 spec is case-insensitive at match time, but every reference site, SEO validator, and Google Search Central example uses the canonical form, and lowercase region codes (en-us) trigger soft warnings in Screaming Frog and Ahrefs Site Audit. The same canonical form is used across the <html lang> attribute, the Content-Language response header, JSON-LD inLanguage, sitemap alternates, and the REST API hreflang field, so all surfaces agree.

Coexistence with SEO plugins

When PerfLocale’s own hreflang is enabled and a supported SEO plugin is active, PerfLocale automatically suppresses the SEO plugin’s native hreflang output so the page never carries two sets of <link rel="alternate"> tags or duplicate Link: response headers:

  • Yoast SEO — add_filter( 'wpseo_output_hreflang', '__return_false' )
  • Rank Math — add_filter( 'rank_math/frontend/disable_hreflang', '__return_true' )
  • AIOSEO — add_filter( 'aioseo_conflicting_shortcodes', '__return_empty_array' )
  • SEOPress, Slim SEO, The SEO Framework — the addons register only sitemap-stage alternates; head-stage hreflang is left to PerfLocale.

Detection runs from both the SEO Plugin setting (explicit) and the plugin’s own constant or class (defensive — covers users who never picked an SEO plugin in PerfLocale’s settings but DO have one active). PerfLocale’s hreflang HTTP Link header is emitted at send_headers priority 1 so its headers land before any SEO plugin’s.

If you want to keep the SEO plugin’s hreflang and disable PerfLocale’s, toggle Hreflang Tags off at Settings → SEO.

Sitemap alternates

PerfLocale hooks into WordPress core’s XML sitemap and attaches <xhtml:link rel="alternate"> entries for translations of every listed URL. If your SEO plugin supplies the sitemap instead, PerfLocale detects that and integrates via its extension point rather than emitting a competing sitemap. No setup needed.

Choosing the sitemap source

The seo_sitemap_source setting (Settings → SEO) selects which sitemap tree carries the xhtml:link alternates when both WP core and an SEO plugin’s native sitemap could serve them:

  • auto (default) — if a supported SEO plugin (Yoast, Rank Math, AIOSEO) is detected, PerfLocale skips the WP core sitemap injection. The SEO plugin’s own sitemap receives the alternates via the per-addon integration. This is the right answer for almost every site.
  • core — always inject into the WP core sitemap, even when an SEO plugin is active. Use this if your SEO plugin’s native sitemap is disabled in its own settings and the core sitemap is the only one being served.
  • plugin — never inject into the WP core sitemap. Use this if you serve a custom or third-party sitemap that PerfLocale doesn’t auto-detect and you want to handle alternates exclusively through it.

For unusual setups, override the auto-detection programmatically with the perflocale/sitemap/inject_into_core filter.

Independent of the source choice, the three SEO sitemap addons (Yoast, Rank Math, AIOSEO) register their entry-capture filters at PHP_INT_MAX so third-party URL-rewriting plugins between priorities 10–999 (canonical-URL plugins, CDN rewriters, etc.) can no longer break PerfLocale’s URL-keyed lookup and silently emit alternates pointing at pre-rewrite URLs.

JSON-LD Schema Enrichment

Adds two small pieces of structured data to whatever JSON-LD your SEO plugin is already emitting: inLanguage (the current page’s language, BCP-47 normalised) and workTranslation (array of URLs pointing at sibling translations). Helps Google surface the right language in search results and lets AI crawlers understand your site’s structure. On by default. See SEO Schema Enrichment for the deep-dive.

Content-Language header

Emits the W3C-standard Content-Language HTTP response header on every frontend request, BCP-47 normalised (de_DE → de-DE). Honoured by Google, Yandex, CDN layers, and some assistive tech in addition to the <html lang> attribute. On by default; filter perflocale/content_language/value customises the value.

data-nosnippet fallback guard

When the Missing Translation Action is set to Show default language, a visitor to /de/mypost/ might see the English content. Without protection, Google indexes that English text under the /de/ URL and shows English snippets in German SERPs. PerfLocale wraps the fallback content with <div data-nosnippet> so Google keeps the URL indexed but omits the mismatched snippet. Only activates when fallback is actually happening. On by default.

IndexNow push-indexing

Tells Bing and Yandex (plus Google via the Cloudflare relay) the moment a translation changes, so indexing happens in hours instead of days. The unique value PerfLocale adds over generic SEO-plugin IndexNow integrations (Rank Math, Yoast) is sibling push: when you edit the English post, PerfLocale also notifies about the German + French siblings whose hreflang alternates just changed - something a generic SEO plugin can’t do because it doesn’t know the translation graph. Disabled by default; enable + auto-generate a 32-char hex key at Settings.

Speculation Rules prerender

When a visitor hovers a language-switcher link, Chromium prerenders the target translation in the background so clicking it feels instant. On WP 6.8+, integrates with Core’s native Speculation Rules API (our rule lands inside Core’s single output script); on older WP, emits a standalone script. Moderate eagerness - prerenders fire only on hover/focus, so visitors who never interact with the switcher never trigger a fetch. Disabled by default.

View Transitions

Smooth 240 ms crossfade between languages using the cross-document View Transitions API (Chrome 126+, Safari 18.2+). Progressive enhancement - unsupported browsers navigate normally. The emitted CSS respects prefers-reduced-motion, zeroing the animation for users with that OS preference (WCAG 2.1 SC 2.3.3). Disabled by default; enable when your theme doesn’t run its own on-navigation animations.

← Back to Docs