The UserWay Accessibility Widget can automatically display in the same language as your website. When Auto-detect is enabled, the widget reads the language declared in your website's HTML and displays the widget interface in the matching language.

⚠️ Important: Auto-detect cannot be used to automatically control the Live Translation add-on. The Live Translation feature does not currently provide an available endpoint or API that can use the page's lang attribute to trigger website translations automatically.

How Language Auto-Detection Works

When Auto-detect is enabled:

The widget reads the lang attribute from your website's root <html> element.
The language value must use a valid ISO 639-1 or BCP 47 language code such as en, es, fr, or pt-BR.
When visitors open the widget, it automatically displays in the matching supported language.
If the lang attribute is missing or contains an unsupported language code, the widget defaults to English.

Example:

<!-- Example of a valid page language declaration -->
<html lang="es">

Configure Language Auto-Detection

Sign in to your UserWay Dashboard at https://manage.userway.org/.
Click My Sites, then click the domain you want to configure.
Open the Customize tab.
Scroll to the Language section, Open the language dropdown and choose Auto-detect.
Click Save to apply the change to the current site, or click Save to All, to apply all sites.

Expected Result

The Accessibility Widget automatically displays in the language defined by your website's HTML lang attribute whenever a visitor opens it.

Troubleshooting

Widget Remains in English

Inspect the rendered page source or use your browser's Developer Tools to verify that the root HTML element contains a valid lang attribute: <html lang="fr">
Confirm that the language value follows a valid ISO 639-1 or BCP 47 format, such as:
- en
- es
- fr
- pt-BR
Verify that the lang attribute is present in the final HTML delivered to the browser, not only in server-side templates or source files.
If a tag manager, JavaScript framework, or client-side application modifies the DOM after page load, confirm that the <html lang="..."> value remains correct after rendering.
Clear browser cache, refresh the page, and reopen the widget. The widget reads the page language when it initializes.

⚠️ Important: If the lang attribute is missing, malformed, or contains an unsupported language code, the widget defaults to English.

Multilingual Website Not Switching Languages

Verify that each localized page updates the root HTML language declaration dynamically. For example:
```
<html lang="en">
<html lang="es">
<html lang="de">
```
Confirm that language changes update the <html lang="..."> attribute before the widget loads.
For single-page applications (SPAs), verify that route changes also update the document's language attribute. The widget may continue displaying the previously detected language if the page language changes without updating the DOM.
Use the browser's Developer Tools to confirm that the current page's <html> element contains the expected language code after navigation.
Refresh the affected page and reopen the widget to verify that the correct interface language is loaded.

Need more help?

Contact the UserWay Support Team — we're here to assist you.

Get in touch with UserWay Support.

How to Automatically Detect Your Website Language in the UserWay Widget