HTML hreflang Attribute

HTML hreflang Attribute

The HTML hreflang attribute identifies the language of a linked resource. It can be used with hyperlinks and certain external resource links to provide language information about the destination.

Syntax

The hreflang attribute is used with an href attribute and contains a language tag identifying the language of the linked resource.

<a href="URL" hreflang="language-tag">Link text</a>

For example, a link to a page written in Spanish can use hreflang="es".

<a href="/es/index.html" hreflang="es">Español</a>

Attribute Value

The hreflang attribute accepts a valid BCP 47 language tag. A language tag can identify a language by itself or provide additional information such as a region.

hreflang="en"
hreflang="es"
hreflang="fr"
hreflang="en-US"
hreflang="en-GB"

Elements That Use the hreflang Attribute

The hreflang attribute can be used with the <a>, <area>, and <link> elements.

The hreflang attribute is meaningful when the element also provides an href value identifying the linked resource.

Using the hreflang Attribute

On an <a> element, hreflang provides advisory information about the language of the destination.

<a href="https://example.com/es/" hreflang="es">Versión en español</a>

The attribute does not translate the destination or force the browser to display a particular language. It describes the language expected at the linked resource.

When the language of the destination is useful to readers, the visible link text can also make that information clear instead of relying solely on the attribute.

Language Tags

A simple language tag identifies a language using a code such as en for English, es for Spanish, or fr for French.

Use a more specific language tag only when the distinction is meaningful. For example, use en-US or en-GB when the linked versions specifically target those regional forms of English.

Using hreflang with the <link> Element

The hreflang attribute is commonly used with <link rel="alternate"> to identify alternate-language versions of a document.

<link rel="alternate" hreflang="en" href="https://example.com/en/">
<link rel="alternate" hreflang="es" href="https://example.com/es/">
<link rel="alternate" hreflang="fr" href="https://example.com/fr/">

Each <link> identifies another version of the document and uses hreflang to describe that version's language. Search engines can use this information when understanding localized or translated versions of pages.

hreflang vs. lang

The hreflang and lang attributes both contain language information, but they describe different things.

<p lang="en">
  Read the
  <a href="/es/index.html" hreflang="es">Spanish version</a>.
</p>

In this example, lang="en" describes the paragraph's language, while hreflang="es" describes the language of the linked destination.

Common Mistakes

Do not use hreflang to identify the language of the link text itself. Use the lang attribute when the text of an element is written in a different language.

<!-- Language of the linked resource -->
<a href="/es/index.html" hreflang="es">Spanish version</a>

<!-- Language of the link text -->
<a href="/es/index.html" lang="es">Español</a>

Do not assume that adding hreflang automatically creates or translates an alternate-language page. The URL must point to an actual resource in the language identified by the attribute.

When using <link rel="alternate"> for localized pages, make sure each href points to the correct language version and each hreflang accurately describes that resource.

Browser Support

Baseline: Widely available indicates a feature has been supported by core browsers for at least 30 months. At this stage, the feature is considered stable and safe for most websites to use without needing to worry about compatibility issues or fallbacks, as it is supported by the vast majority of users' devices and browser versions.

The hreflang attribute is widely supported on the elements where it applies. It is commonly used with <a> and <link> elements to identify the language of a linked resource.

Checking Browser Support

For current browser compatibility information, visit Can I Use? . Search for the HTML element or attribute you want to check. You can also narrow your search by entering an element name and attribute name separated by a colon. Search results can include related HTML features, element attributes, input types, APIs, and other technologies, so select the result that most closely matches the feature you are checking.

Try the hreflang Attribute

The example contains links whose hreflang values identify the language of each destination. Change the language tags and link destinations in the editor to experiment with the attribute.

Summary

The HTML hreflang attribute identifies the language of a linked resource. It can be used with the <a>, <area>, and <link> elements and accepts a valid language tag such as en, es, or en-US. The attribute describes the language of the destination rather than the language of the element's own text.