A visitor in Mexico should not land on your English checkout page. A buyer in Canada should not be forced onto a UK product page with the wrong currency, shipping rules, or spelling. That is the real job of hreflang: it helps search engines understand which version of a page best serves each audience. If you are learning how to add hreflang WordPress correctly, the goal is not to add more code. It is to create clear, matching language and regional signals across every translated URL.
For a small bilingual site, this can be straightforward. For a store, agency site, or multilingual content library with hundreds of products and pages, a poor setup can create duplicate signals, broken alternates, and costly indexing confusion. Start with the site structure, then choose the implementation method that your team can reliably maintain.
What hreflang does for a WordPress website
Hreflang is an HTML attribute that tells Google and other search engines that multiple URLs are alternate versions of the same content. Each tag specifies a language, and optionally a region. For example, `en-us` targets English speakers in the United States, while `es-mx` targets Spanish speakers in Mexico.
It does not automatically translate content, change a visitor’s language, or guarantee rankings. It helps search engines select the most relevant localized page from pages that are substantially similar in purpose. That is particularly useful when you publish English pages for the US, Canada, Australia, and the UK, or translated versions of a service, product, or blog post.
Use a language-only code such as `es` when one Spanish version is intended for all Spanish-speaking markets. Use a language-region pairing such as `es-us` only when the page is genuinely tailored for that regional audience. Creating dozens of country versions with nearly identical content just to cover every market usually adds maintenance work without adding value.
Plan your URL and language structure first
Before adding a plugin or editing a theme, decide how each language will live on the site. WordPress multilingual sites commonly use subdirectories, such as `example.com/es/`, subdomains, such as `es.example.com`, or separate country domains. All three can work with hreflang.
Subdirectories are often the most practical choice for WordPress owners because one installation, one theme, and one SEO workflow can manage the site. Separate domains can make sense when each regional business needs independent inventory, pricing, teams, or legal content. The trade-off is more technical administration and a greater chance that translated pages drift out of sync.
Map the pages before launch. Your English pricing page needs a Spanish counterpart if you intend to declare them as alternates. If a translated page does not exist, do not point hreflang at a homepage or a loosely related category page. Hreflang pairs equivalent pages, not merely pages in the same language.
How to add hreflang WordPress with a multilingual plugin
For most WordPress sites, a multilingual plugin is the safest route. Tools such as WPML, TranslatePress, and Polylang can create language versions, connect their translations, and generate hreflang tags in the page source. The exact screens differ by plugin, but the operational process is similar.
First, install your multilingual solution and set a default language. Add only the languages and regional variants you can support with real content. Then choose your URL format and translate the main navigation, pages, posts, product categories, WooCommerce products, checkout notices, and SEO metadata where applicable.
The critical step is linking each translation to its matching original. Do not create a Spanish page as a separate, unconnected page and assume WordPress will know what it represents. In the translation editor or language panel, assign the translated version to the correct source page. Once those relationships are saved, the plugin can output alternate tags such as:
“`html “`
Open the public page, view its source, and search for `hreflang`. You should see a tag for the current page and each connected translation. Repeat the check on the translated page. The same language set should appear there too.
For agencies managing several builds, using a maintained premium multilingual plugin is usually cheaper than repairing custom language logic later. A GPLWPStore membership can be useful for accessing WordPress tools across client projects, but always confirm that the plugin version supports your WordPress, WooCommerce, and SEO plugin setup before deploying it on a live site.
Add hreflang manually only when you control the logic
Manual hreflang can be appropriate for a custom WordPress build, a headless architecture, or a site with a simple fixed set of localized landing pages. It is not usually a good shortcut for a growing site. Every new post, product, redirect, or deleted translation becomes another relationship to update.
If you add tags in a custom theme, place them in the document “ and generate URLs dynamically rather than hard-coding them where possible. Your code must output the self-referencing URL and every alternative URL for each page. In other words, the English page must reference Spanish, and the Spanish page must reference English.
Do not add a second manual set if your multilingual or SEO plugin already generates hreflang. Duplicate tags with different URLs or codes make the signal unclear. Pick one system of record and document it for everyone who publishes content.
For non-HTML files, such as PDFs, hreflang can be delivered through HTTP headers. XML sitemaps can also carry hreflang annotations. These options are useful for specialized technical setups, but HTML tags are generally easier for WordPress teams to inspect and maintain. Avoid mixing methods unless your developer has a clear reason and keeps every implementation consistent.
Use the right language, region, canonical, and x-default values
Hreflang values use a language code first and an optional region code second. Use `en-us`, `en-gb`, `fr-ca`, or `pt-br` where regional targeting is intentional. Do not use country codes alone, such as `us`, because hreflang needs a language.
Each localized page should generally have a self-referencing canonical URL. The US English page should canonically point to itself, and the Mexican Spanish page should canonically point to itself. A common mistake is setting the Spanish page’s canonical to the English original. That tells search engines the Spanish page is not the preferred standalone URL, which works against the purpose of hreflang.
Add `x-default` when you have a sensible fallback page for people whose language or region is not specifically covered. This may be a language selector or your primary international English page. It should not be a random redirect page. If English is only for the United States, do not label it as `x-default` unless it truly serves everyone else reasonably well.
Test before and after publishing
Hreflang problems often appear after an innocent change: a page slug is updated, a translation is moved to draft, a staging site is cloned, or a redirect plugin changes the destination. Build hreflang validation into your normal WordPress maintenance routine.
Check that every URL returns a 200 status, uses the correct preferred URL format, and is indexable. A page blocked by robots settings, marked `noindex`, or redirected elsewhere is not a useful alternate. Make sure each alternate relationship is reciprocal and that language selectors lead to the matching page rather than always sending visitors to a homepage.
For ecommerce, test more than blog posts. Check variable products, product categories, cart and account pages, search result behavior, and filtered URLs. You may decide not to index certain utility pages, but that decision should be deliberate and consistent across languages.
Google Search Console can surface language and indexing issues after crawling, while a page-source review catches basic mistakes immediately. When you change URL structures or migrate a multilingual site, test a representative sample of high-value pages first: homepage, service page, top product, category, blog post, and conversion page.
Common hreflang mistakes that waste traffic
The most damaging error is connecting pages that are not true equivalents. If a German category page points to an English homepage, search engines receive an incomplete and misleading relationship. Create the correct counterpart, or leave the alternate out until it exists.
Another frequent issue is automatic geo-redirecting. Redirecting every visitor based only on IP location can prevent search engines and travelers from accessing the version they choose. A visible language and country selector is usually a better customer experience. If you use redirects, make them optional and avoid trapping users in one version.
Finally, do not confuse translation quality with technical markup. Hreflang can help the right page appear, but it cannot make thin machine-translated copy persuasive. Localize product details, currencies, delivery information, measurements, and calls to action when those details affect a buyer’s decision.
A clean hreflang setup is quiet when it is working: the right page is available, the tags agree, and your team can add a new translation without creating a technical cleanup project. Build that repeatable workflow now, and every new market page becomes easier to publish with confidence.