Components Language toggle
The language toggle component lets the user switch between two languages when using a service. It is used in the Toggle to Welsh pattern to switch between English and Welsh.
<nav class="dwp-language-toggle" aria-label="Language toggle">
<ul class="dwp-language-toggle__list">
<li class="dwp-language-toggle__list-item" aria-current="true">
English
</li>
<li class="dwp-language-toggle__list-item">
<a href="#"
hreflang="cy"
lang="cy"
rel="alternate"
class="govuk-link"
aria-label="Newid yr iaith ir Gymraeg">Cymraeg</a>
</li>
</ul>
</nav>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.
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.
| Name | Type | Description |
|---|---|---|
| selectedLang | string | Used to switch between langauges - defaults to English. |
| href | object | Required.Object for setting urls |
{% from "language-toggle/macro.njk" import dwpLanguageToggle %}
{{
dwpLanguageToggle({
selectedLang: "en",
href: {
en: "#",
cy: "#"
}
})
}}When to use this component
Use the language toggle when a service is available in two different languages and the user can switch between them while using the service.
When not to use this component
Do not use this component to switch between more than two languages.
How it works
The component presents the two language options in their own language, separated by a pipe character, with the default language listed first. The second language is an active link which triggers the change.
When the second language is selected, the default language becomes an active link which changes the language back to the default.
The mechanism for changing language when the link is selected will depend on how your service is built.
You should put the toggle on the right-hand side of the page, below the GOV.UK header and phase banner.
<nav class="dwp-language-toggle" aria-label="Togl iaith">
<ul class="dwp-language-toggle__list">
<li class="dwp-language-toggle__list-item">
<a href="#"
hreflang="en"
lang="en"
rel="alternate"
class="govuk-link"
aria-label="Change the language to English">English</a>
</li>
<li class="dwp-language-toggle__list-item" aria-current="true">
Cymraeg
</li>
</ul>
</nav>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.
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.
| Name | Type | Description |
|---|---|---|
| selectedLang | string | Used to switch between langauges - defaults to English. |
| href | object | Required.Object for setting urls |
{% from "language-toggle/macro.njk" import dwpLanguageToggle %}
{{
dwpLanguageToggle({
selectedLang: "cy",
href: {
en: "#",
cy: "#"
}
})
}}Accessibility
To meet WCAG 2.2 success criteria 3.1.1 Language of page and 3.1.2 Language of parts you should make sure the language attribute has been applied properly. This helps things like screen readers to pronounce the content correctly.
In an English/Welsh service this would work as follows.
In the English version of the service:
- the page’s default language must be set to English with
<html lang=en> - the link text ‘Cymraeg’ must be set to Welsh with
lang=cy
In the Welsh version of the service:
- the page’s default language must be set to Welsh with
<html lang=cy> - the link text ‘English’ must be set to English with
lang=en
The inactive toggle text does not need a separate language attribute because it is in the default language of the page.
For more about building accessible services see the DWP Accessibility Manual.
Research
Research on an English/Welsh language toggle from HMRC and from the Universal Credit service found that users liked to be able to toggle between Welsh and English throughout a service to sense check their understanding, especially for unfamiliar words. This was true even for fluent Welsh speakers.
Contribute
If you have used or researched this component, please let us know what you found so we can make it better for everyone. There is an open discussion for this component on GitHub where you can share anything you think might be useful.
Discuss Language toggle on GitHub
Get in touch
If you’ve got a question, idea or suggestion email the Design System team on dwp-design-system@engineering.digital.dwp.gov.uk