Language navigation

Trial

This component is being developed and may change as we improve it. Read more about the lifecycle of our components.

Read these sections to see why this component is in trial:

The Language navigation component helps users choose and switch between languages when using a service.

Open this example in a new tab: language navigation
HTML
<nav class="govuk-language-navigation" aria-label="Language">
  <ul class="govuk-language-navigation__list">
    <li class="govuk-language-navigation__list-item">
      <span class="govuk-language-navigation__text"
        aria-current="true" lang="en">English</span>
    </li>
    <li class="govuk-language-navigation__list-item">
      <a class="govuk-language-navigation__link" href="#" rel="alternate" lang="cy" hreflang="cy">Cymraeg </a>
    </li>
  </ul>
</nav>
Nunjucks
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description. Deprecated options are marked as “Deprecated”.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
items array Required. The languages to display within the language navigation. See macro options for items.
ariaLabel string Plain text label identifying the navigation landmark to screen readers. Write it in the language of the current page. Defaults to “Language”.
classes string Classes to add to the language navigation container.
attributes object HTML attributes to add to the language navigation container.
Options for items array objects
Name Type Description
text string Required. If html is set, this is not required. Name of the language, written in that language (for example, “Cymraeg” for Welsh). If html is provided, the text option will be ignored.
html string Required. If text is set, this is not required. HTML to use for the language item. If html is provided, the text option will be ignored.
lang string Required. The language tag for the language item text (for example, cy for Welsh). Added as a lang attribute so that assistive technologies pronounce the language name correctly.
hrefLang string The language tag for the linked page (for example, cy for Welsh). Added as an hreflang attribute for search engines and other machine readers. Defaults to lang when omitted.
dir string The text direction of the script the language name is written in (ltr for left-to-right scripts or rtl for right-to-left). Set this on every item if the navigation includes scripts written in different directions.
href string Link to the current page in this language.
current boolean Whether this is the language of the current page. Defaults to true when href is not provided.
languageDescriptionText string Visually hidden text after a language link to indicate what the link will do. Write it in the language of the link (for example, “Change the language to English”).
classes string Classes to add to the language item anchor.
attributes object HTML attributes to add to the language item anchor. 
{% from "govuk/components/language-navigation/macro.njk" import govukLanguageNavigation %}

{{ govukLanguageNavigation({
  items: [
    {
      text: "English",
      lang: "en",
      href: "#",
      current: true
    },
    {
      text: "Cymraeg",
      lang: "cy",
      href: "#"
    }
  ]
}) }}

When to use this component

Use the Language navigation component when you can provide your service in more than one language.

For example, to help users switch from a page in English to a version of the same page in Welsh.

How you use this component will depend on whether you offer a choice of languages for:

When not to use this component

Do not use this component unless you can provide all the same key information on a page in another language.

How it works

The Language navigation component shows users a choice of languages and helps the user choose and switch between them.

Use the native name of each language, such as Cymraeg for Welsh. This helps speakers of that language recognise the link.

The component does not translate content. You’ll need to create, test and maintain content for all the languages you offer your service in.

See some of the other things you might need to do as part of designing services that offer multiple languages.

Make sure the user does not lose any data they’ve entered when they navigate to another language. Do not ask the user to re-enter information they’ve already given.

Placement on pages

Where you place the Language navigation component helps users understand whether they can use your entire service or only specific pages in another language.

Choose a single consistent location that works best for your users.

Use the same placement throughout your service in all languages. This helps users in many ways. For example, some users often switch languages throughout their journey as a way to check their understanding of a page.

If you only offer specific pages in another language

You could place the language navigation at the top of a page, after the h1 element.

If you choose to place the language navigation elsewhere on a page, it should be in a sensible place in the page heading structure with its own visible or hidden heading.

Open this example in a new tab: language navigation after h1
HTML
<div class="govuk-width-container">
  <main class="govuk-main-wrapper " id="main-content" role="main">
    <!--
    Note the override class adding the same margin
    as the heading would have to this `<div>`
  -->
    <div class="govuk-!-margin-bottom-8">
      <!--
      Note the override class setting a smaller margin between
      the heading and the Language navigation
    -->
      <h1 class="govuk-heading-xl govuk-!-margin-bottom-3">Find protected areas of countryside</h1>
      <nav class="govuk-language-navigation" aria-label="Language">
        <ul class="govuk-language-navigation__list">
          <li class="govuk-language-navigation__list-item">
            <span class="govuk-language-navigation__text"
              aria-current="true" lang="en">English</span>
          </li>
          <li class="govuk-language-navigation__list-item">
            <a class="govuk-language-navigation__link" href="#" rel="alternate" lang="cy" hreflang="cy">Cymraeg </a>
          </li>
        </ul>
      </nav>
    </div>
    <p class="govuk-body">Nature sites and areas of countryside can be ‘designated’, which means they have special status as protected areas because of their natural and cultural importance.</p>
    <p class="govuk-body">...</p>
  </main>
</div>
Nunjucks
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description. Deprecated options are marked as “Deprecated”.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
items array Required. The languages to display within the language navigation. See macro options for items.
ariaLabel string Plain text label identifying the navigation landmark to screen readers. Write it in the language of the current page. Defaults to “Language”.
classes string Classes to add to the language navigation container.
attributes object HTML attributes to add to the language navigation container.
Options for items array objects
Name Type Description
text string Required. If html is set, this is not required. Name of the language, written in that language (for example, “Cymraeg” for Welsh). If html is provided, the text option will be ignored.
html string Required. If text is set, this is not required. HTML to use for the language item. If html is provided, the text option will be ignored.
lang string Required. The language tag for the language item text (for example, cy for Welsh). Added as a lang attribute so that assistive technologies pronounce the language name correctly.
hrefLang string The language tag for the linked page (for example, cy for Welsh). Added as an hreflang attribute for search engines and other machine readers. Defaults to lang when omitted.
dir string The text direction of the script the language name is written in (ltr for left-to-right scripts or rtl for right-to-left). Set this on every item if the navigation includes scripts written in different directions.
href string Link to the current page in this language.
current boolean Whether this is the language of the current page. Defaults to true when href is not provided.
languageDescriptionText string Visually hidden text after a language link to indicate what the link will do. Write it in the language of the link (for example, “Change the language to English”).
classes string Classes to add to the language item anchor.
attributes object HTML attributes to add to the language item anchor. 
{% from "govuk/components/language-navigation/macro.njk" import govukLanguageNavigation %}

{% block content %}
  <!--
    Note the override class adding the same margin
    as the heading would have to this `<div>`
  -->
  <div class="govuk-!-margin-bottom-8">
    <!--
      Note the override class setting a smaller margin between
      the heading and the Language navigation
    -->
    <h1 class="govuk-heading-xl govuk-!-margin-bottom-3">Find protected areas of countryside</h1>
    {{ govukLanguageNavigation({
      items: [
        {
          text: "English",
          lang: "en",
          href: "#",
          current: true
        },
        {
          text: "Cymraeg",
          lang: "cy",
          href: "#"
        }
      ]
    }) }}
  </div>
  <p class="govuk-body">Nature sites and areas of countryside can be ‘designated’, which means they have special status as protected areas because of their natural and cultural importance.</p>
  <p class="govuk-body">...</p>
{% endblock %}

If you offer your whole service in another language

If users can change the language for your whole service, you can place the Language navigation component into the Service navigation component.

The Service navigation component includes options to align the language navigation with navigation items as shown in this example.

Open this example in a new tab: service navigation with inline end slot – service navigation
HTML
<section aria-label="Service information" class="govuk-service-navigation"
  data-module="govuk-service-navigation">
  <div class="govuk-width-container govuk-service-navigation__inlining-container">
    <div class="govuk-service-navigation__container">
      <span class="govuk-service-navigation__service-name">
        <a href="#" class="govuk-service-navigation__link">
          Service name
        </a>
      </span>
      <nav aria-label="Menu" class="govuk-service-navigation__wrapper">
        <button type="button" class="govuk-service-navigation__toggle govuk-js-service-navigation-toggle" aria-controls="navigation" hidden aria-hidden="true">
          Menu
        </button>
        <ul class="govuk-service-navigation__list" id="navigation">
          <li class="govuk-service-navigation__item">
            <a class="govuk-service-navigation__link" href="#">
              Item 1
            </a>
          </li>
          <li class="govuk-service-navigation__item govuk-service-navigation__item--active">
            <a class="govuk-service-navigation__link" href="#" aria-current="true">
              <strong class="govuk-service-navigation__active-fallback">Item 2</strong>
            </a>
          </li>
        </ul>
      </nav>
    </div>
    <nav class="govuk-language-navigation" aria-label="Language">
      <ul class="govuk-language-navigation__list">
        <li class="govuk-language-navigation__list-item">
          <span class="govuk-language-navigation__text"
            aria-current="true" lang="en">English</span>
        </li>
        <li class="govuk-language-navigation__list-item">
          <a class="govuk-language-navigation__link" href="#" rel="alternate" lang="cy" hreflang="cy">Cymraeg </a>
        </li>
      </ul>
    </nav>
  </div>
</section>
Nunjucks
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description. Deprecated options are marked as “Deprecated”.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
classes string Classes to add to the service navigation container.
attributes object HTML attributes (for example, data attributes) to add to the service navigation container.
ariaLabel string The text for the aria-label which labels the service navigation container when a service name is included. Defaults to "Service information".
menuButtonText string The text of the mobile navigation menu toggle.
menuButtonLabel string The screen reader label for the mobile navigation menu toggle. Defaults to the same value as menuButtonText if not specified.
navigationLabel string The screen reader label for the mobile navigation menu. Defaults to the same value as menuButtonText if not specified.
navigationId string The ID used to associate the mobile navigation toggle with the navigation menu. Defaults to navigation.
navigationClasses string Classes to add to the navigation menu container.
collapseNavigationOnMobile boolean Whether the navigation should be collapsed inside a menu on mobile. Defaults to true if there is more than one navigation item.
serviceName string The name of your service.
serviceUrl string The homepage of your service.
navigation array Required. Used to add navigation to the service header. See macro options for navigation.
slots object Specified points for injecting custom HTML into the service header. See macro options for slots.
Options for navigation array objects
Name Type Description
current boolean If true, indicates that the user is currently on this page. This takes precedence over active.
active boolean If true, indicates that the user is within this group of pages in the navigation hierarchy.
html string Required. HTML for the navigation item. If html is provided, the text option will be ignored.
text string Required. Text for the navigation item. If html is provided, the text option will be ignored.
href string URL of the navigation item anchor.
attributes object HTML attributes (for example data attributes) to add to the navigation item anchor.
Options for slots object
Name Type Description
start string HTML injected at the start of the service header container.
end string HTML injected at the end of the service header container.
end object Options for injecting HTML at the end of the service header container. See macro options for slots end.
navigationStart string HTML injected before the first list item in the navigation list. Requires navigation to be set.
navigationEnd string HTML injected after the last list item in the navigation list. Requires navigation to be set.
Options for slots end object
Name Type Description
html string HTML injected at the end of the service header container.
align string By default, the end slot renders below the navigation items. Use inline to render it on the same line as the navigation items when space is available. 
{% from "govuk/components/service-navigation/macro.njk" import govukServiceNavigation %}
{% from "govuk/components/language-navigation/macro.njk" import govukLanguageNavigation %}

{% set languageNavigationHtml %}
  {{ govukLanguageNavigation({
    items: [
      {
        text: "English",
        lang: "en",
        href: "#",
        current: true
      },
      {
        text: "Cymraeg",
        lang: "cy",
        href: "#"
      }
    ]
  }) }}
{% endset %}

{{ govukServiceNavigation({
  serviceName: "Service name",
  serviceUrl: "#",
  navigation: [
    {
      href: "#",
      text: "Item 1"
    },
    {
      href: "#",
      text: "Item 2",
      active: true
    }
  ],
  slots: {
    end: {
      html: languageNavigationHtml,
      align: 'inline'
    }
  }
}) }}

Ensure hidden text and attributes are in the correct languages

The code in this component contains a navigation landmark and some hidden text to help users, including users of assistive technology. Make sure to translate these attributes as needed.

aria-label (or ariaLabel in Nunjucks) labels the component’s navigation landmark. By default the label is ‘language’, which will be announced by a screen reader as ‘language navigation’. Translate this label to the language of the page it’s on.

Hidden text within the link for each language option (or languageDescriptionText in Nunjucks) explains what the link will do. For example, ‘Change the language to English’. Translate these to the language you’re linking to.

Language navigation on dark backgrounds

Use the govuk-language-navigation--inverse modifier class to show white links and text on a dark background – for example, inside a Service navigation with a dark background.

Make sure all users can see the language navigation – the background colour must have a contrast ratio of at least 4.5:1 with white to meet WCAG 2.2 success criterion 1.4.3 Contrast (minimum), level AA.

Open this example in a new tab: invers language navigation - language navigation
HTML
<nav class="govuk-language-navigation govuk-language-navigation--inverse" aria-label="Language">
  <ul class="govuk-language-navigation__list">
    <li class="govuk-language-navigation__list-item">
      <span class="govuk-language-navigation__text"
        aria-current="true" lang="en">English</span>
    </li>
    <li class="govuk-language-navigation__list-item">
      <a class="govuk-language-navigation__link" href="#" rel="alternate" lang="cy" hreflang="cy">Cymraeg </a>
    </li>
  </ul>
</nav>
Nunjucks
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description. Deprecated options are marked as “Deprecated”.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
items array Required. The languages to display within the language navigation. See macro options for items.
ariaLabel string Plain text label identifying the navigation landmark to screen readers. Write it in the language of the current page. Defaults to “Language”.
classes string Classes to add to the language navigation container.
attributes object HTML attributes to add to the language navigation container.
Options for items array objects
Name Type Description
text string Required. If html is set, this is not required. Name of the language, written in that language (for example, “Cymraeg” for Welsh). If html is provided, the text option will be ignored.
html string Required. If text is set, this is not required. HTML to use for the language item. If html is provided, the text option will be ignored.
lang string Required. The language tag for the language item text (for example, cy for Welsh). Added as a lang attribute so that assistive technologies pronounce the language name correctly.
hrefLang string The language tag for the linked page (for example, cy for Welsh). Added as an hreflang attribute for search engines and other machine readers. Defaults to lang when omitted.
dir string The text direction of the script the language name is written in (ltr for left-to-right scripts or rtl for right-to-left). Set this on every item if the navigation includes scripts written in different directions.
href string Link to the current page in this language.
current boolean Whether this is the language of the current page. Defaults to true when href is not provided.
languageDescriptionText string Visually hidden text after a language link to indicate what the link will do. Write it in the language of the link (for example, “Change the language to English”).
classes string Classes to add to the language item anchor.
attributes object HTML attributes to add to the language item anchor. 
{% from "govuk/components/language-navigation/macro.njk" import govukLanguageNavigation %}

{{ govukLanguageNavigation({
  classes: 'govuk-language-navigation--inverse',
  items: [
    {
      text: "English",
      lang: "en",
      href: "#",
      current: true
    },
    {
      text: "Cymraeg",
      lang: "cy",
      href: "#"
    }
  ]
}) }}

Designing services that offer multiple languages

GOV.UK Content and publishing guidance gives some advice on things you need to consider when translating content.

Test your service with users in your intended language to spot potential issues such as word inaccuracies and cultural differences. The Service Manual for Wales shows how you can consider bilingualism in your research.

Internationalisation and localisation

If you choose to show larger parts of your service in another language, consider if you need to translate the text within components such as navigation, buttons and accordions.

Our components use English by default but include methods to translate text within them. Follow our documentation on how to localise GOV.UK Frontend.

For some languages, you’ll need to modify components to make sure text displays well and is understandable by users of assistive technologies. For example, to show languages using scripts that read from right to left, such as Arabic, you’ll need to make changes to components and layouts.

See W3C’s introduction to internationalisation for more about some of the things you might need to consider.

Keep in mind that language and regional differences can affect the format users expect to see and enter information such as names, numbers and addresses.

Research on this component

We’ve released this Language navigation component in trial status.

Thank you to the teams in departments across government who worked with us to contribute and share their research to get the component to this point.

We know from research contributed that users:

  • want the option to change language to be easy to find and recognise
  • want data to persist so they can navigate between languages and understand unfamiliar words
  • want navigating languages across government services to be consistent
  • want to change the language for a whole journey or page whilst moving through a service

Share your research

If you use this component, we’d like to get your feedback to help us improve it.

We’d particularly like to know more about how different services use language navigation and how well users find it.

Until we’re confident we’re providing well-defined guidance for services to use language navigation consistently in a way that meets user needs, we’ll keep this component in trial status.

Help improve this component

Trial

In August 2026 we moved Language navigation to trial status so we can learn how well it works for services.

See the information we're looking for and how you can help move this component into stable status:

Tell us how well Language navigation works in your service

You can also:

Need help?

If you’ve got a question about the GOV.UK Design System, contact the team.