Patterns: Select a language

Three or more languages

Help a user choose from multiple available languages.

This pattern helps users, especially those with limited English proficiency, select their preferred language when visiting a website available in three or more languages, like English, Spanish, and Arabic.

About this pattern

What problem does this solve?

Inconsistent placement and treatment of language selection interface components can be a barrier to users, especially those with limited English-language skills, preventing them from easily finding and accessing content in other languages.

When to use this pattern

Use this pattern when the content is available in three or more languages and all content is available in each language.

When to consider something else

When content is available in only two languages, see the Select from two languages pattern. When only selected multilingual content is available in some languages, see the Selected content available pattern.

What’s the solution?

Place the language selector menu at the top of the screen above site navigation, allowing site visitors to use a dropdown menu to select their language of choice. Place the language selector on the top right for left-to-right languages and on the top left for right-to-left languages if possible.

Guidance

What to do

  • Place the language menu button in the upper corner of the screen for consistency. If possible, flip the arrangement of the header for right-to-left languages. The language button should be positioned at the top right of the page for left-to-right languages and on the top left for right-to-left languages.
  • Make the language access button a single, independent element.
  • Include the language dropdown in the header so that it remains visible and in the same position as the user scrolls up and down a webpage if the website has a “sticky” or “fixed” header.
  • Take users to an equivalent page that includes the same or similar content.
  • Label the dropdown menu Languages.
  • Capitalize the name of each language (for example, English, Español).
  • Do order the languages alphabetically by the common, native language name. For example:
    العربية (Arabic)
    简体字 (Chinese - Simplified)
    English
    Español (Spanish)
    Français (French)
    Italiano (Italian)
    Pусский (Russian)

What not to do

  • Do not create a dead end for users by taking them to a page with little or no meaningful content.
  • Strongly consider whether including icons or graphics on the language selection button offers communication value, as these may represent different concepts to different cultures.
  • Do not use flags or country codes to indicate languages. Flags do not map to languages; Arabic, for example, is spoken in many countries. The country code ES may not be universally understood to indicate Spanish.
  • Avoid auto-redirecting language based on detecting location or browser settings. This can be confusing and disorienting.
  • Do not combine this element with other navigation items.
<div class="usa-language-container usa-language--small">
  <ul class="usa-language__primary usa-accordion">
    <li class="usa-language__primary-item">
      <button class="usa-button usa-language__link" role="button" aria-expanded="false"
        aria-controls="language-options">
        Languages
      </button>
      <ul id="language-options" class="usa-language__submenu" hidden="true">
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="العربية | Arabic"><span lang="ar"
            xml:lang="ar"><strong>العربية</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="简体字 | Chinese (Simplified)"><span lang="zh"
            xml:lang="zh"><strong>简体字</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="English | English"><span lang="en"
            xml:lang="en"><strong>English</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="Español | Spanish"><span lang="es"
            xml:lang="es"><strong>Español</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="Français | French"><span lang="fr"
            xml:lang="fr"><strong>Français</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="Italiano | Italian"><span lang="it"
            xml:lang="it"><strong>Italiano</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="Pусский | Russian"><span lang="ru"
            xml:lang="ru"><strong>Pусский</strong></span></a>
        </li>
      </ul>
    </li>
  </ul>
</div>
<div class="usa-language-container usa-language--small">
  <ul class="usa-language__primary usa-accordion">
    <li class="usa-language__primary-item">
      <button class="usa-button usa-language__link" role="button" aria-expanded="false"
        aria-controls="language-options">
        Languages
      </button>
      <ul id="language-options" class="usa-language__submenu" hidden="true">
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="العربية | Arabic"><span lang="ar"
            xml:lang="ar"><strong>العربية</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="简体字 | Chinese (Simplified)"><span lang="zh"
            xml:lang="zh"><strong>简体字</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="English | English"><span lang="en"
            xml:lang="en"><strong>English</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="Español | Spanish"><span lang="es"
            xml:lang="es"><strong>Español</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="Français | French"><span lang="fr"
            xml:lang="fr"><strong>Français</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="Italiano | Italian"><span lang="it"
            xml:lang="it"><strong>Italiano</strong></span></a>
        </li>
        <li class="usa-language__submenu-item">
          <a href="javascript:void()" title="Pусский | Russian"><span lang="ru"
            xml:lang="ru"><strong>Pусский</strong></span></a>
        </li>
      </ul>
    </li>
  </ul>
</div>

Usability guidance

  • Consider including a prominent in-page notice or link in addition to the link in the header, in order to increase visibility for the user.
  • Ensure there’s enough color contrast between the button, the text inside the button, and the site background to ensure readability.

Accessibility

  • If the text will be visually presented as a button but coded as a link, it is recommended to add ARIA role=”button” so that screen readers announce it as a button. Additionally, JavaScript will also need to be added so that keyboard users can activate the button using both the Enter and Spacebar keys. See Understanding Success Criterion 4.1.2 - Understanding WCAG 2.0 for more information.
  • Use the HTML lang attributes to set the language of the page (<html lang='en'>, for example). See H57: Using the language attribute on the HTML element for more information.
  • All logically related items and links must be presented as an HTML unordered list.

See pattern in use

References

Disclaimer

Links to nongovernment sources are made for educational or source citation purposes only, and do not represent an endorsement of the organizations by the General Services Administration. The General Services Administration does not assume any responsibility for the content, operation, or policies of other entities’ websites.

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2022-11-14 3.3.0
  • Guidance
No

Pattern published.