Enter a page's canonical URL and each of its language or region versions. The tool outputs the matching tags as HTML, Next.js metadata, sitemap XML, or an HTTP header, and flags common setup errors.
Canonical URL (this page)
Hreflang entries (language and region URLs)
Entries
3
Warnings
0
No issues found. These checks don't cover return links on your other pages, so review the final tags before you publish.
Generated code
Paste these tags inside the <head> of this page.
<link rel="canonical" href="https://example.com/en/" /> <link rel="alternate" hreflang="en" href="https://example.com/en/" /> <link rel="alternate" hreflang="es" href="https://example.com/es/" /> <link rel="alternate" hreflang="x-default" href="https://example.com/en/" />
How hreflang and canonical tags work
A canonical tag tells search engines which URL is the preferred version when several URLs show the same or very similar content, such as a page with tracking parameters or a print version. Search engines treat it as a strong hint, not a command.
Hreflang annotations list the language and region versions of a page so search engines can show each searcher the right one. Each version should list itself and all the others.
Enter your canonical URL and your language versions, and the tool writes the tags in four formats: HTML <link> elements, Next.js metadata, sitemap XML, and an HTTP Link header. It flags duplicate codes, a missing x-default, relative URLs, malformed codes, and a canonical URL that isn't in your list. It doesn't fetch your pages, so it can't check that the other versions link back.
Situations where you need these tags
Launching a translated or regional page
List every version once and get the full set of alternate links to paste into each version's head. Change only the canonical URL for each page.
Cleaning up duplicate URLs
Set a canonical for URLs that differ only by parameters, trailing slash, or a print layout. Leave the hreflang list empty and you get the canonical tag alone.
Adding metadata in Next.js App Router
Copy a ready-to-paste metadata object with alternates.canonical and alternates.languages, typed with the Metadata type.
Annotating a sitemap or a PDF
Generate sitemap XML where every language version has its own url entry, or a Link header for files that have no HTML head.
Set up your URLs and copy the code
- Enter the canonical URL of the page you're tagging. Use a full URL that starts with https://.
- Add each language or region version under the hreflang entries. Use the code buttons, add rows by hand, or paste lines in the form code,URL.
- Add an x-default entry for your fallback page, and make sure the page itself is in the list.
- Fix any warnings, choose HTML, Next.js, Sitemap XML, or HTTP header, and copy the code.
- Repeat for every other version of the page. Keep the hreflang list the same and change only the canonical URL to that version's own address.
Note: Everything runs in your browser. The URLs you enter are not sent to a server.
Before you paste the code
- The warnings are checks based on common implementation rules. Your site may have a valid reason to break one, so review the final output yourself.
- The tool doesn't crawl your site. It can't confirm that the other versions link back or that the URLs return a 200 status.
- Use full URLs with https://. Relative paths such as /es/ are not valid for alternate URLs.
- Pick one method for a given set of pages (HTML, sitemap, or HTTP header) so the sources can't disagree.
- Sitemap output includes the xhtml namespace and one url entry per version, each listing the full set of alternates.
Language and region code cheat sheet (en-US, es-MX, zh-Hans)
Common values for the hreflang attribute. Use a language code alone when you don't target a specific region.
| Code | Meaning | Code | Meaning |
|---|---|---|---|
| en | English (any region) | es | Spanish (any region) |
| en-US | English (United States) | es-MX | Spanish (Mexico) |
| en-GB | English (United Kingdom) | fr | French |
| en-CA | English (Canada) | pt-BR | Portuguese (Brazil) |
| de | German | ja | Japanese |
| zh-Hans | Chinese (Simplified script) | zh-Hant | Chinese (Traditional script) |
| ko | Korean | x-default | Fallback for all other searchers |
Language codes follow ISO 639-1 and region codes follow ISO 3166-1 alpha-2. Write them with a hyphen, as in en-US, not en_US. The United Kingdom's region code is GB, so use en-GB.
Canonical vs. alternate: what each tag tells search engines
The ideas behind the tags, and how to choose between the output formats.
Canonical picks a preferred URL; hreflang maps the versions
rel=canonical answers “which URL should count when several show the same content?” rel=alternate with hreflang answers “which URL matches this searcher’s language or region?”
On a localized page you use both: each version has a canonical pointing to itself, plus the same set of hreflang links. Google treats fully translated pages as localized versions rather than duplicates.
Self-reference and return links
Each version must list itself as well as every other version. If page A lists page B, page B should list page A. A one-way link may be ignored.
This is the mistake that is easiest to miss on large sites, because the error is on a different page from the one you edited.
What x-default is for
x-default is the fallback for searchers whose language doesn't match any entry. Google suggests adding one, especially for language selectors and homepages that redirect automatically.
Use your language selector page, or the version you want unmatched visitors to see.
HTML, HTTP header, or sitemap
Google accepts all three. HTML link elements go in the page's head. An HTTP Link header is for files without an HTML head, such as PDFs. A sitemap keeps the markup out of the page, and every version needs its own url entry listing the full set of alternates.
Choose one method per set of pages.
Next.js App Router: alternates.canonical and alternates.languages
Export a metadata object, or a generateMetadata function for dynamic routes, with alternates.canonical and alternates.languages. Next.js renders them as link tags in the head.
Quote the "x-default" key like any other language code. The Next.js tab in this tool produces exactly this structure.
Mistakes that make search engines ignore the tags
Using relative URLs
Writing href="/es/" instead of a full URL. Alternate URLs must be fully qualified, including https://.
💡 See the solution▼
Leaving out the return links
The English page lists the Spanish page, but the Spanish page doesn't list the English one, so the pair may be ignored.
💡 See the solution▼
Pointing every canonical at one language
A template sets the canonical of all translated pages to the English URL, which tells search engines the translations are duplicates of it.
💡 See the solution▼
Forgetting x-default or the self-reference
The list has no fallback entry, or the page's own URL is missing from its own list.
💡 See the solution▼
Writing codes in the wrong format
Values such as en_US (underscore) or jp for Japanese are not valid hreflang codes, and a country code such as UK is not a language code.
💡 See the solution▼
FAQ: x-default, return links, and Next.js setup
Q.What is an hreflang tag and when do I need one?
A. An hreflang annotation tells search engines which language or regional versions of a page exist, so they can show searchers the version that fits. You need it when the same page is available in more than one language or for more than one region, such as /en/ and /es/, or separate US and UK English pages.
Q.What does a canonical tag do, and how is it different from hreflang?
A. A canonical tag (rel="canonical") names the preferred URL when several URLs show the same or very similar content, for example a URL with tracking parameters. Hreflang does a different job: it links the language and region versions of a page to each other. Localized pages are normally tagged with both, and each version's canonical points to its own URL.
Q.What is x-default, and do I have to add it?
A. x-default marks the fallback page for searchers whose language or region doesn't match any hreflang entry. It is usually a language selector or the default homepage. Google treats it as a recommendation, not a requirement, and this tool warns you if it's missing.
Q.Does every language version need to list all the others?
A. Yes. Each version should list itself and every other version, and if page A points to page B, page B should point back to page A. Add the same set of hreflang links to every version, and change only the canonical URL to match that version's own address.
Q.Should I use HTML tags, a sitemap, or an HTTP header?
A. Google accepts all three. HTML link tags in the <head> are the most common choice. A sitemap suits large sites because it keeps the annotations out of the page markup. An HTTP Link header is the option for non-HTML files such as PDFs. Pick one method for a given set of pages so your sources can't contradict each other.
Q.How do I add canonical and hreflang tags in Next.js?
A. In the App Router, export a metadata object (or a generateMetadata function) with alternates.canonical and alternates.languages. Next.js renders them as link tags in the page head. Choose the Next.js tab in this tool and paste the result into your page or layout file.
Q.Does hreflang improve my rankings?
A. Not directly. Hreflang doesn't make a page rank higher. It helps search engines pick the right language or regional version of a page for each searcher, which can reduce wrong-language results.
Q.Are the URLs I enter sent to a server?
A. No. The tool runs entirely in your browser. The URLs and language codes you enter are not sent or stored anywhere, and they disappear when you close or reload the page.
Your feedback
makes this tool better.
Tell us which features you'd like, what should be fixed, or which new tool you'd like to see. An engineer reads every submission and uses it to guide development.