Home / / Language Detection & Redirects

Language Detection & Redirects

18 views

Every page load on a multilingual WPResidence site needs an answer to one question: which language should this visitor see? The WPResidence Translate plugin answers that question in a specific order, remembers the visitor’s choice, and protects against redirect loops that plague naive multilingual setups. This article explains the detection order, the cookie behavior, and the redirect safeguards. For a broader overview of running a multi-language real estate website, see our main guide.

The Detection Order

For every front-end request, WPResidence Translate works through this list top-to-bottom and uses the first winner:

  1. Language slug in the URL — if the URL starts with a recognised language prefix (e.g. /es/), that wins.
  2. Language preference cookie — a cookie named wpestate_translation_lang_pref from the visitor’s previous session.
  3. Browser Accept-Language header — the language list the browser sends, sorted by quality, matched against your active languages.
  4. Default language — the language you marked as default on the Languages page.

The URL always wins. If a visitor clicks /fr/about-us/, they get French even if their cookie says Spanish. This keeps shared links predictable: a link sent to a colleague shows the same language on both ends.

How Cookies Work

When a visitor clicks your language switcher, the plugin stores their choice in the wpestate_translation_lang_pref cookie. The cookie:

  • Lasts one month.
  • Is set for the site’s cookie path and domain (and mirrored to the site cookie path when the two differ).
  • Is marked HttpOnly and uses the Secure flag on HTTPS sites.

The cookie is only written when the language is explicitly chosen — either by clicking the switcher or by landing on a language-prefixed URL. Fallback languages inferred from the browser header do not overwrite an existing cookie. This avoids the common bug where a German visitor briefly previews English and loses their German preference on the next click.

Browser Language Matching

When there is no URL prefix and no cookie, WPResidence Translate reads the visitor’s Accept-Language header. It parses each entry with its quality score (q=), sorts them from highest to lowest, and tries each one against your active languages. It accepts:

  • Full matches: en-US against a locale of en_US.
  • Short matches: pt against a language with code pt or pt-br.
  • Slug matches: browser fr against the language whose slug is fr.

If none match, the visitor sees the default language.

The <html> lang Attribute

WPResidence Translate stamps the current language onto the document so assistive tech and search engines pick it up. Beyond the native <html lang=”…”> that WordPress emits, the plugin also adds a data-wpr-language attribute to the <body> tag via a small inline script. This is mostly useful for automated tests and analytics segmentation.

Redirect Loops — and How They Are Prevented

Multilingual sites are a common source of redirect loops: WordPress’s canonical redirect tries to strip the language prefix, the plugin re-adds it, the browser follows, the server strips it again, and so on. WPResidence Translate has two specific safeguards:

  • Prefix canonical protection — if WordPress proposes a canonical redirect that only toggles a language slug on or off, the plugin cancels it.
  • Front-page safeguard — if a visitor requests /es/ but the Spanish front page is not translated yet, the plugin refuses to collapse the URL back to / . The visitor sees the default content under the Spanish prefix, the language switcher keeps working, and the URL stays stable.

Both behaviors are automatic — no setting required.

SEO Tags: Canonical & hreflang

To help search engines understand your multilingual setup, the plugin emits the right <link> tags in the page head:

  • A rel=”canonical” tag pointing to the current language version.
  • A rel=”alternate” hreflang=”…” tag for each translated variant, including the current language.

If Yoast SEO or Rank Math is installed, the plugin hands those URLs over to their filter pipelines so the two systems do not fight. No configuration is required on your end.

Troubleshooting Checklist

  • Wrong language on first visit — check Settings → Detect browser language.
  • Stuck on one language — clear the wpestate_translation_lang_pref cookie for your site and reload.
  • Redirect loop after adding a language — visit Settings → Permalinks and click Save to flush rewrite rules.
  • Visitor says hreflang is missing — make sure the translation actually exists and is published; hreflang is only emitted for real translations.

What To Read Next

  • URL Structure & Permalinks — the shape of the URLs that detection operates on.
  • Rewrite Rules & Query Vars — the developer view of the routing layer.
  • Language Switcher Widget — the front-end control that writes the cookie.

For the full product tour, see our multi-language real estate website guide.