Support
SEORuns locally

Hreflang Generator and Validator

Add language and regional page versions, check common hreflang mistakes, and generate implementation-ready annotations without uploading your URLs.

New to hreflang? Read the step-by-step beginner guide

01

Build the complete alternate set

Use only substantially equivalent language or regional versions of the same page.

Waiting for alternate pages
02

Current page URL

Optional, and used only for a local self-reference check.

When supplied, the exact normalized URL should appear among the non-x-default entries.

03

Alternate pages

Start with two rows, then add, duplicate, remove, or reorder as needed.

Language: two- or three-letter primary code, optionally with a valid hyphen-separated subtag such as zh-Hans.

Region: optional two-letter country code. GB means the United Kingdom; it is not a language.

URL: an absolute HTTP or HTTPS page URL. Paths, queries, and fragments are preserved.

Label: optional working note shown only in this editor and never added to generated output.

x-default: optional fallback for unmatched users; only one row can use it.

Structure-only validation: Foxger validates URL and code structure only. It does not check whether submitted pages exist, are indexable, or return a successful HTTP status.

04

Validation summary

Add equivalent alternate pages, then generate the complete set.

05

Generated output

Choose one implementation format and maintain the same complete set consistently.

HTML alternate link tags

Usually the simplest method for ordinary HTML pages. Place the complete set in the document head.

0 characters

After generation

What should I do with this output?

Choose one format your website can maintain, install the complete set on the equivalent pages, and check the live implementation separately. The guide below explains each step from the beginning.

Start the beginner guide
Step-by-step guide

Learn hreflang from the beginning

This guide explains the idea, the form, the generated code, and the checks that still need human review. You do not need previous Search Engine Optimization (SEO) or coding knowledge.

Back to the generator
Beginner guide contents
Start here

Hreflang in one minute

Imagine a website has the same guide in English and Spanish. Both pages teach the same topic, but each one serves readers who use a different language.

Hreflang is a label that tells a search engine those pages are language alternatives. The search engine can use that relationship when deciding which version may suit a searcher.

Hreflang does not

  • translate a page;
  • redirect a visitor;
  • guarantee indexing, traffic, or rankings;
  • replace clear language navigation or a language selector.
Make the first decision

Do you need hreflang?

Ask whether the pages are language or regional versions of substantially the same page. A matching topic, design, or menu is not enough by itself.

Hreflang may be appropriate

  • The same article exists in English and Spanish.
  • The same product page serves English readers in the US and UK.
  • The same documentation page exists in Japanese and English.
  • Country-specific pages contain mostly equivalent information.
  • Equivalent pages are on different subdomains or domains.

Hreflang is probably not the answer

  • The site has only one language.
  • The pages discuss different topics or have different purposes.
  • One page is a summary and the other is a different article.
  • You want a tool to translate the page automatically.
  • You want to redirect visitors by country.
  • You only need to declare the language of one HTML page.
Prepare first

Before you use the generator

Collect these details before entering rows:

  • the full URL of every equivalent page;
  • the language used by each page;
  • an optional target region, only when the page is genuinely regional;
  • the URL of the current page;
  • a decision about whether an x-default fallback is useful;
  • a decision about where the generated code can be installed.
Correct: full URLhttps://example.com/guides/solar-system/
Incorrect: missing hostname/guides/solar-system/
Incorrect: missing protocolexample.com/guides/solar-system/
Read the form

Understand every field

Each field has one job. The page label is the only field that never appears in generated code.

Current page URL Optional

Enter the full address of the page you are working on. Foxger compares it with the non-x-default rows to check for an exact self-reference. Foxger does not visit the URL. Without this value, it can offer guidance but cannot confirm that the current page is in the set.

Language code Required

Identify the page language. Common values include en for English,es for Spanish, de for German, fr for French, and ja for Japanese. A language code is not a country code.

Region code Optional

Narrow a language version to an intended region. Examples include US,GB, MX, and BR. Use it because the content targets that audience, not because the website owner lives there.

Alternate page URL Required

Enter the complete address of that page, starting with https:// orhttp://. Aim at the final preferred URL. Foxger checks its structure but does not open the page, follow redirects, or test its status.

Page label Optional, tool only

Add a friendly working note such as “English page” or “Spanish page.” It helps you manage rows inside Foxger and is not included in HTML, HTTP, or XML output.

Mark as x-default Optional

Use this for one fallback page, such as a language chooser or global page. The row must not also contain a language or region. x-default is optional, and English should not be selected automatically as the fallback.

XML sitemap output type Shown in the XML output tab

Choose XML fragment when adding the generated blocks to an existing sitemap whose parent urlset includes the XHTML namespace. ChooseFull minimal sitemap document when you need a small standalone sitemap file containing this set. Your site may still need to connect that file to its sitemap setup.

Row and example controls

  • Add alternate creates another empty page row.
  • Duplicate copies a row so you can edit a similar version.
  • Move up and Move down change the order used in generated output.
  • Remove deletes that row. Foxger keeps at least one usable row area.
  • Load example fills a separate “Getting Started” sample set for practice.
  • Clear all removes the entered rows and generated output from the page.

Small x-default example

English page → en

Spanish page → es

Language chooser → x-default

Build the value

How a language tag is built

A basic tag starts with the language. Add a region only when it describes the page.

enlanguage
GBoptional region

The hyphen is the separator. Foxger displays the language in lowercase and a two-letter region in uppercase. BCP 47 comparisons are case-insensitive, so this capitalization is a clear convention rather than a change in meaning.

Incorrect separatoren_US
Correcten-US
Incorrect for UK EnglishUK
Correcten-GB
IncorrectEnglish
Correcten

en means general English. en-GB means English content intended for the United Kingdom. It does not mean “British language.”

Advanced note: scripts and broader language tags

BCP 47 can include a script and other registered subtags. For example,zh-Hans identifies Chinese written in the Simplified script, whilezh-Hant identifies Chinese written in the Traditional script.

A script and a region describe different choices. Foxger does not guess betweenzh-CN, zh-TW, zh-Hans, or zh-Hant. Its check is structural; it does not confirm every subtag in the IANA registry or promise that every structurally valid BCP 47 tag is supported by every search engine.

One example from start to finish

Complete beginner example

A fictional educational site has the same “Solar System Guide” in English, Spanish, and German. It also has a language selector. These four URLs stay the same throughout this guide.

English
https://example.com/guides/solar-system/
Spanish
https://example.com/es/guias/sistema-solar/
German
https://example.com/de/ratgeber/sonnensystem/
Language selector
https://example.com/languages/
  1. Enter the current pagehttps://example.com/guides/solar-system/
  2. Add EnglishLanguage en · Region blank · English URL
  3. Add SpanishLanguage es · Region blank · Spanish URL
  4. Add GermanLanguage de · Region blank · German URL
  5. Add x-defaultSelect x-default · Language and region blank · Language-selector URL
  6. GenerateExpect no blocking errors, an English self-reference, four alternate values, and output in HTML, HTTP-header, and XML-sitemap formats.
Use the tool with confidence

Follow along in 8 steps

Each step gives you one action, the reason for it, and a useful check before you continue.

  1. Decide which pages belong together

    What to do: Choose pages that give readers substantially equivalent information.

    Why: Hreflang describes alternate versions of one page, not a group of loosely related pages.

    Check: Group the English, Spanish, and German Solar System guides—not a planet guide and an astronomy news page.

  2. Add the full current-page URL

    What to do: Paste the address of the page you are working on into Current page URL.

    Why: Foxger can then check whether that page appears in its own alternate set.

    Check: Use https://example.com/guides/solar-system/, not the relative path /guides/solar-system/.

  3. Enter every language version

    What to do: Use one row for each equivalent page, adding more rows when needed.

    Why: The generated set should describe the whole group you intend to implement.

    Check: For this guide, enter en, es, and de with their three full URLs. Leave no extra partly completed row.

  4. Add regions only when they describe the audience

    What to do: Use Region only when a page intentionally serves a regional audience.

    Why: A region narrows a language version; it does not identify the language by itself.

    Check: Language en plus Region GB becomes en-GB. A country code never replaces the language field.

  5. Add x-default only when useful

    What to do: Mark one fallback or language-selector row as x-default, if your site has one.

    Why: It gives search engines a fallback for users who do not match the listed choices.

    Check: The Solar System set uses https://example.com/languages/. Leave x-default out when there is no suitable fallback.

  6. Read validation by severity

    What to do: Fix errors first, then review every warning and information note.

    Why: Errors block output; warnings allow output but flag a choice; information adds context.

    Check: A deliberate mixed-hostname set can still be valid, while a missing required URL must be corrected.

  7. Generate and review one output format

    What to do: Select Generate annotations, then choose HTML, HTTP Link header, or XML sitemap output.

    Why: One method your site can maintain is clearer than several inconsistent copies.

    Check: The Solar System result includes en, es, de, and x-default. Generated syntax does not mean Foxger visited those URLs.

  8. Install and verify the complete set

    What to do: Place the same complete group on each equivalent page using your chosen method.

    Why: Each page should normally name itself and return the links from its alternates.

    Check: Review the live English, Spanish, and German pages separately for deployment, reciprocal links, URL accuracy, and canonicals.

Back to the generator

Read the summary

Errors, warnings, and information mean different things

Error

An error blocks reliable output and should be fixed.

Examples: invalid URL, missing language, duplicate hreflang value, or more than one x-default.

Warning

A warning allows output but asks you to review a possible risk or intentional choice.

Examples: mixed hostnames, missing self-reference, no x-default, or one URL used for several values.

Information

Information explains a choice or a check Foxger cannot complete.

For example, without a current-page URL, Foxger gives general self-reference guidance.

Foxger can check entered URL and language-tag structure, duplicates, and exact self-reference when you supply the current page URL. It cannot visit the pages to confirm deployment, reciprocal live tags, canonicals, indexability, or search-engine processing.

Create the set

Generate your code

  1. Review every row and correct blocking errors.
  2. Select Generate annotations.
  3. Read the validation summary before copying anything.
  4. Open the HTML, HTTP header, or XML output tab.
  5. Copy the output, or download it with Foxger’s fixed safe filename.

Generation happens in your browser. After review, the result is code to place using your chosen method; it is not proof of live deployment. Foxger does not visit the destinations, check whether they exist, or add the output to your website.

Choose a method

Choose an output format

Google supports HTML tags, HTTP Link headers, and XML sitemap annotations. Choose the method that your website can implement correctly and keep updated.

Often a direct first implementation

HTML tags

Usually the most direct choice for ordinary HTML webpages. Add the lines inside the page’s<head>, the part of an HTML document that holds page metadata and settings. Every equivalent page should normally contain the complete set.

<link rel="alternate" hreflang="en" href="https://example.com/guides/solar-system/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/guias/sistema-solar/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/ratgeber/sonnensystem/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/languages/" />
Useful for some non-HTML files

HTTP Link header

The web server sends this metadata with the resource. It can be useful for files such as PDFs, but it usually requires server or hosting configuration and is not the most direct first choice for an ordinary webpage.

Link: <https://example.com/guides/solar-system/>; rel="alternate"; hreflang="en", …
Useful for centrally managed or larger sites

XML sitemap

A sitemap is a structured file that lists site URLs for search engines. Each localized page block normally contains the complete alternate set. The parent sitemap needs the XHTML namespace.

<url>
  <loc>https://example.com/guides/solar-system/</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/guides/solar-system/" />
  <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/guias/sistema-solar/" />
  <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/ratgeber/sonnensystem/" />
  <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/languages/" />
</url>

Google treats the supported methods as equivalent. Maintaining more than one gives you more copies to keep in sync. One consistent method is often clearer unless there is a practical reason to use another.

Put the code in the right place

Install the HTML output

The generated <link> lines belong inside the document’s <head>.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Solar System Guide</title>

    <!-- Paste the generated hreflang tags here -->
  </head>
  <body>
    <h1>Solar System Guide</h1>
  </body>
</html>
  • Do not paste the tags into the visible article text.
  • Do not paste them into a normal page editor unless it supports custom head code.
  • Website builders and content-management systems use different installation methods.
  • You may need an internationalization setting, SEO setting, template, trusted plugin, or developer.
Include the page itself

Self-reference and return links

On the English page, the generated set still includes the English line. The page includes itself in the language group so the complete set is clear.

<link rel="alternate" hreflang="en" href="https://example.com/guides/solar-system/" />

English page lists

English · Spanish · German · x-default

Spanish page lists

English · Spanish · German · x-default

German page lists

English · Spanish · German · x-default

Two tools, two jobs

Hreflang and canonical tags

A canonical tells search engines which URL is the preferred version among duplicate or near-duplicate URLs. Hreflang tells them which localized versions belong together. The two signals are related, but they are not interchangeable.

Canonical: Which URL is the preferred copy of this page?

Hreflang: Which language or regional version may suit this user?

A common pattern for fully localized pages is:

English page canonical → English page
Spanish page canonical → Spanish page
German page canonical → German page

Then all three pages participate in the same hreflang set.

Review before publishing

Check your work

First review the data in Foxger. Then inspect the live implementation separately.

Check the entered data

  • Every page is an equivalent version.
  • Every URL is complete.
  • Language values are correct.
  • Optional regions are intentional.
  • No language tag contains an underscore.
  • No language-region value is duplicated.
  • There is no more than one x-default.
  • The current page appears in the set.

Check the installed output

  • The complete set is installed.
  • Every equivalent page returns the corresponding links.
  • URLs point to final preferred pages.
  • Pages can be crawled and return successful responses.
  • Canonical tags support the localized pages.
  • The code is in a supported location.
  • The XHTML namespace exists in sitemap output.
Pause before publishing

Common mistakes

Items marked “Manual check” describe content choices or live-site details that Foxger cannot test.

  1. Connecting unrelated pagesManual check

    A shared topic or layout does not make pages alternatives. Connect only pages with substantially equivalent purpose and main information.

  2. Using a country code as the languageManual check

    A country alone does not identify the page language. Use en-GB for English intended for the United Kingdom; Foxger’s structural check cannot infer that choice for you.

  3. Writing en_US

    The underscore makes the tag invalid here. Enter language en and region US to generate en-US.

  4. Leaving out the current page

    The set can miss its self-reference. Enter Current page URL so Foxger can compare it with the non-x-default rows, then include that page.

  5. Publishing incomplete return linksManual check

    A one-way relationship may not be processed reliably. Install the relevant reciprocal set on the alternate pages, not only the starting page.

  6. Reusing one URL for several values

    The audience mapping may be unintended. Review Foxger’s warning and give each language or regional version its accurate URL.

  7. Treating English as automatic x-defaultManual check

    English is not automatically the fallback. Choose a suitable fallback deliberately, or omit x-default when none is needed.

  8. Creating several x-default entries

    Foxger blocks output because one set can contain no more than one x-default value. Keep one or remove them.

  9. Confusing hreflang with canonicalManual check

    The signals answer different questions. Review each localized page’s canonical separately instead of pointing every version to one language by habit.

  10. Assuming generated code is already liveManual check

    Valid output proves only that Foxger could build code from the entered structure. Check deployment, return tags, canonicals, responses, and indexability on the website.

  11. Using an outdated or redirected URLManual check

    The generated syntax can still point to the wrong destination. Replace it with the accurate final preferred page URL where possible.

Solve a message calmly

Troubleshooting

Open the problem that matches what you see.

“Foxger says my URL is invalid”

Check whether it starts with https:// or http://, contains an accidental space, is incomplete, or uses an unsupported protocol.

“Foxger says I have a duplicate hreflang value”

Only one URL should be assigned to a particular value, such as es, within one alternate set. Remove the duplicate or correct the language or region.

“Foxger says the current page is missing”

Add the current page as its own non-x-default language version. Make sure its full URL exactly matches the value in Current page URL.

“My pages use different domains”

This can be valid. Confirm that the pages are equivalent and that every domain implements the complete reciprocal set. Foxger warns so you review the choice.

“I do not have a language-selector page”

Leave out x-default. It is optional, not a requirement.

“I use only English and Spanish”

Two equivalent versions can form a set. Add en for the English URL and es for the Spanish URL, then install both annotations on both pages.

“I have English for the US and UK”

Use en-US and en-GB when the pages genuinely target those regions. A general en fallback may help some content strategies, but it is not universally mandatory.

“My website builder does not let me edit the head”

Check its SEO, internationalization, template, or sitemap settings. A trusted platform extension or developer may be needed. Do not paste tags into visible page text.

Look up a word

Glossary

Alternate page
A language or regional version of another page with substantially equivalent content.
Canonical URL
The URL a page identifies as the preferred version among duplicate or near-duplicate URLs.
Country or region code
An optional subtag that narrows a language version to a region, such as GB in en-GB.
Fully qualified URL
A complete web address that includes the protocol and hostname, such as https://example.com/page/.
HTML
HyperText Markup Language is the code that gives a webpage its structure.
HTTP header
Information a web server sends with a resource before the browser receives its content.
Hreflang
An annotation that identifies alternate language or regional versions of a page.
Indexing
The process by which a search engine stores and organizes information about a page for possible search results.
Language code
A short registered subtag that identifies a language, such as en for English or es for Spanish.
Localized page
A page adapted for a language or regional audience. Translation may be part of that work.
Reciprocal link
A return annotation from one alternate page back to the page that named it.
Redirect
A server or browser instruction that sends a visitor from one URL to another. Hreflang is not a redirect.
Search engine
A service that discovers, organizes, and helps people find information on the web.
Self-reference
An annotation in which a page includes its own URL as one member of the alternate set.
Sitemap
A file that lists site URLs and can include extra information for search engines.
URL
Uniform Resource Locator: the address used to find a page or resource on the web.
x-default
An optional fallback hreflang value for users who do not match another listed language or region.
XML
Extensible Markup Language is a text format used to organize structured data, including sitemaps.
Optional practice

Try a small language-tag exercise

Open the practice activity

A fictional guide has these versions:

  • General English: https://example.com/learn/stars/
  • US English: https://example.com/us/learn/stars/
  • Spanish: https://example.com/es/aprender/estrellas/

Which hreflang values should you enter? Should a separate language selector be marked en or x-default?

Show the answer

Use en, en-US, and es.

A separate language selector can use x-default because it is the fallback, not the English page. x-default remains optional.

One last review

Ready to generate?

  • My pages are equivalent versions.
  • I copied each full URL.
  • I chose the correct language.
  • I added a region only when needed.
  • I used hyphens instead of underscores.
  • I included the current page.
  • I used no more than one x-default.
  • I reviewed all errors and warnings.
  • I chose one suitable output format.
  • I understand that the complete set belongs on each equivalent page.
  • I will check canonicals, redirects, and indexability separately.
Back to the Hreflang Generator
FAQ

Hreflang questions

Does Foxger check whether my URLs are live?

No. Foxger validates URL structure locally but does not visit submitted URLs, check HTTP status codes, inspect redirects, or confirm indexability.

Is x-default required?

No. x-default is optional. It is commonly used for a language selector, global page, or fallback for users who do not match another language or region.

Should every hreflang page reference itself?

Pages should generally include a self-referencing annotation as part of the complete alternate set. Foxger can compare an optional current page URL with the set, but it cannot inspect the live page.

Can different hreflang URLs use different domains?

Yes, different domains can be valid. Foxger shows a cautious mixed-hostname warning so you can review the set, not because different domains are automatically wrong.

Should translated pages use the same canonical URL?

Localized pages usually use self-referencing canonicals. Hreflang does not replace canonical tags, and canonicalizing every translation to one language page can conflict with localization goals.

Can I use both language and country codes?

Yes. A language value such as en means general English, while en-GB means English content intended for the United Kingdom. A country code does not identify a language by itself.

Should I add hreflang in HTML and a sitemap?

Use the method your team can implement consistently. Google treats the supported methods as equivalent, while maintaining duplicate implementations can add avoidable complexity.

Is en_US a valid hreflang value?

No. Hreflang values use hyphens rather than underscores. Enter en as the language and US as the optional region to generate en-US.

Optional support

Help keep Foxger useful

Foxger tools are free, private, and built without display ads. Optional support helps keep them maintained, tested, and documented.

Support Foxger
Related tools
MarketingUTM Campaign URL BuilderBuild encoded campaign links without visiting them.Text & SEOSlug GeneratorCreate consistent URL paths for localized content.DirectoryAll Foxger toolsBrowse every available and planned utility.
Primary-source research

Official references

The guide summarizes these official sources in original language. External links open in a new tab.