Guides

Language Override

Suggest Edits

Overview

By default, JOIN widgets automatically detect the visitor's language from the browser (navigator.language) or the page's <html lang="..."> attribute, and display the matching story variants.

The data-join-language attribute lets you force a specific language on the widget script tag, bypassing automatic detection. This is useful when your website manages language independently from the browser or the <html> tag.

Usage

Add data-join-language to your widget <script> tag:

<script
  type="text/javascript"
  src="https://cdn.stories.studio/widgets/my-alias/index.js"
  data-join-widget-id="my-widget"
  data-join-widget-alias="my-alias"
  data-join-language="fr"
></script>

Default behavior (without the attribute)

Without data-join-language, the widget resolves the language in this order:

  1. jDataLayer — if a language key is pushed via the data layer
  2. navigator.language — browser language (e.g. fr-FR → fr)
  3. Fallback — en

The widget also observes changes to <html lang="..."> at runtime and re-renders automatically when the language changes (useful for SPAs with dynamic language switching).

When data-join-language is set

  • Automatic language detection is disabled for this widget instance
  • The <html lang="..."> observer is not started
  • The specified language is used for every render

Example

<!-- French widget -->
<div id="widget-fr"></div>
<script
  type="text/javascript"
  src="https://cdn.stories.studio/widgets/my-alias/index.js"
  data-join-widget-id="widget-fr"
  data-join-widget-alias="my-alias"
  data-join-language="fr"
></script>

Note: If the specified language has no matching story variant, the widget falls back to the default story unless disableStoryLanguageFallback is enabled in the widget configuration.

Updated about 9 hours ago