The HTML hreflang attribute

Attribute All modern browsers

By David AdamsUpdated November 4, 2026

In short

On a link, hreflang="de" says the page it points to is in German. Any valid BCP 47 language tag is allowed, such as en, pt-BR or zh-Hans, and browsers treat it only as a hint. Paired with rel="alternate" on an <a> or <link>, it can mark a translation of the current page.

Overview

The HTML hreflang attribute states what language a linked page or file is written in. Links made with <a> or <link> take it when they have an href, while its place on <area> is still unsettled.

The HTML standard bars browsers from treating hreflang as authoritative, so once the linked page arrives, they go by the language information that comes with it. On its own, hreflang has no built-in functionality.

Its value is a BCP 47 language tag made of subtags joined by hyphens. The common ones are a two- or three-character language such as de, an optional four-character script such as Hans in zh-Hans, and an optional region such as BR in pt-BR or 013 in es-013.

In the head, <link rel="alternate" hreflang="de" href="https://example.com/de/"> gives hreflang one more job. When its value differs from the page's language, the linked document counts as a translation, and translations listed together are alternates of each other.

Syntax

<a href="/de/" hreflang="de" lang="de">Deutsch</a>
<a href="/pt-br/" hreflang="pt-BR">Portuguese (Brazil)</a>

Values

Value
A BCP 47 language tag, such as `en`, `fr` or `pt-BR`.

Example

 Live example
                                    
                                    
                                        
                                        
                                        
                                    
                                

                                    
                                

                                    <div lang="en">
  <p>Point at a link, Tab to it or click it to compare lang and hreflang.</p>
  <p>
    <a href="https://example.com/de/" hreflang="de" lang="de">Deutsch</a> |
    <a href="https://example.com/fr/" hreflang="fr" lang="fr">Fran&ccedil;ais</a> |
    <a href="https://example.com/pt-br/" hreflang="pt-BR" lang="pt-BR">Portugu&ecirc;s (Brasil)</a>
  </p>
  <p><a href="https://example.com/de/guide/" hreflang="de">Read this guide in German</a></p>
  <p id="msg" role="status">No link chosen yet.</p>
</div>
<script>
const msg = document.getElementById('msg');
function show(event) {
  const link = event.target.closest('a');
  if (!link) return;
  if (event.type === 'click') event.preventDefault();
  const textLang = link.closest('[lang]').lang;
  msg.textContent = 'The text "' + link.textContent + '" is in ' + textLang + ' (lang). The page it opens is in ' + link.hreflang + ' (hreflang).';
}
for (const type of ['mouseover', 'focusin', 'click']) document.addEventListener(type, show);
</script>
                                

Best practices

Take the hreflang value from the target page's own lang, such as pt-BR on both. Then the hint never contradicts the page.
Join subtags with hyphens, as in en-US. Both en_US and a full name such as english fail validation on validator.nu.
Select links by language with a[hreflang|="pt"], which matches pt, pt-BR and pt-PT. Attribute selectors treat hreflang values as case-insensitive, so PT-br matches as well.
Don't expect :lang() to read hreflang, since it matches an element's own language. On an English page, a:lang(de) matches a link with lang="de" but not one with only hreflang="de".

Accessibility

Frequently asked questions

What does the hreflang attribute describe?

The hreflang attribute describes the language of the page a link leads to, such as de for German.

What values can hreflang take?

The hreflang attribute takes one BCP 47 language tag, such as en, en-GB, zh-Hans or es-013. The language comes first, followed by an optional script and an optional region, all joined by hyphens.

Should a link use lang or hreflang?

A link can use both, since lang covers its text and hreflang covers the linked page. A link whose English text points to a German page takes hreflang=de but no lang attribute.

Is hreflang only for SEO?

No, hreflang is plain HTML, and stylesheets and scripts can use it on any anchor or link element. Google Search reads it on link rel=alternate elements in the head under rules of its own, which add an x-default value and don't support codes such as es-419.

What does the hreflang property return in JavaScript?

Reading hreflang in JavaScript gives you the attribute's text unchanged, on anchors and on link elements. A missing attribute reads as an empty string, and the property doesn't check that the tag is valid.

Can image map areas use hreflang?

Not reliably yet, because hreflang on area is experimental and supported only in Firefox 153 and later. The HTML standard's area section lists it, but its attribute index doesn't, and its obsolete-features section says to omit it.

href http-equiv

References