Multilingual Support

Ekoo supports multilingual audio content, allowing you to serve audio in the right language based on your visitor's locale.

How It Works

When you set the data-ekoo-locale attribute on a widget, Ekoo filters audio content to show only tracks tagged with that locale. If no locale is specified, the widget uses auto-detection based on the browser's language settings.

Locale Attribute

Set the locale directly on the widget element:

French locale

html

1<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
2
3<ekoo-widget
4  data-ekoo="YOUR_WEBSITE_ID"
5  data-ekoo-product-id="YOUR_PRODUCT_ID"
6  data-ekoo-locale="fr"
7></ekoo-widget>

English locale

html

1<ekoo-widget
2  data-ekoo="YOUR_WEBSITE_ID"
3  data-ekoo-product-id="YOUR_PRODUCT_ID"
4  data-ekoo-locale="en"
5></ekoo-widget>

Supported Locale Values

⚠️

Ekoo uses its own locale codes

Ekoo locale codes may differ from standard ISO/BCP47 codes. For example: Chinese Simplified is cn (not zh-Hans), Japanese is jp (not ja), Korean is kr (not ko). See the Locale Mapping section below if your site uses standard codes.

Value	Language
`fr`	French
`en`	English
`es`	Spanish
`it`	Italian
`de`	German
`da`	Danish
`ar`	Arabic
`cn`	Chinese (Simplified)
`tw`	Chinese (Traditional)
`hk`	Chinese (Hong Kong)
`jp`	Japanese
`kr`	Korean
`nl`	Dutch
`tr`	Turkish
`pl`	Polish
`pt`	Portuguese
`lu`	Luxembourgish
`be`	Belgian (French)
`ru`	Russian

Auto Detection

If the data-ekoo-locale attribute is omitted, Ekoo checks navigator.language and matches the best available audio. If no match is found, it falls back to showing all available audio for the product.

Automatic language detection

html

1<ekoo-widget
2  data-ekoo="YOUR_WEBSITE_ID"
3  data-ekoo-product-id="YOUR_PRODUCT_ID"
4  data-ekoo-locale="auto"
5></ekoo-widget>

No filtering (all languages)

By omitting the data-ekoo-locale attribute, all published audios for the product will be accessible regardless of locale:

No locale filtering

html

1<ekoo-widget
2  data-ekoo="YOUR_WEBSITE_ID"
3  data-ekoo-product-id="YOUR_PRODUCT_ID"
4></ekoo-widget>

JavaScript Configuration

The locale can also be set via window.ekooOptions. The locale goes inside the widgets array (not as a top-level property):

Locale via ekooOptions

javascript

1// window.ekooOptions sets the locale for programmatic widget creation
2window.ekooOptions = {
3  websiteId: "YOUR_WEBSITE_ID",
4  widgets: [
5    {
6      nodeId: "my-container",
7      productId: "my-product",
8      locale: "fr"
9    }
10  ]
11};

Setting Locale Dynamically

You can change the locale at runtime by updating the attribute and reloading the widget:

Dynamic locale change

javascript

1const widget = document.querySelector('[data-ekoo]');
2widget.setAttribute('data-ekoo-locale', getUserLocale());
3window.ekooReload();

React Example

In a React application, you can pass the locale as a prop and trigger a reload when it changes:

React locale integration

tsx

1import { useEffect } from 'react';
2
3interface EkooWidgetProps {
4  websiteId: string;
5  productId: string;
6  locale?: string;
7}
8
9export function EkooWidget({ websiteId, productId, locale }: EkooWidgetProps) {
10  useEffect(() => {
11    window.ekooReload();
12  }, [locale]);
13
14  return (
15    <ekoo-widget
16      data-ekoo={websiteId}
17      data-ekoo-product-id={productId}
18      data-ekoo-locale={locale}
19    ></ekoo-widget>
20  );
21}

Locale Mapping

If your site uses standard BCP47 or ISO language codes (e.g., zh-Hans, ja, ko), you may need a mapping script to convert them to Ekoo locale codes. Add this script before the Ekoo widget script:

Locale mapping script

html

1<script>
2// Locale mapping: your site codes → Ekoo codes
3// Add this BEFORE the Ekoo widget script
4(function() {
5  var mapping = {
6    // BCP47 / ISO  →  Ekoo code
7    'zh-hans': 'cn',  // Chinese Simplified → cn
8    'zh-hant': 'tw',  // Chinese Traditional → tw
9    'ko':      'kr',  // Korean → kr
10    'ja':      'jp',  // Japanese → jp
11  };
12
13  var ekooLocales = [
14    'fr', 'en', 'es', 'it', 'de', 'ar',
15    'cn', 'tw', 'hk', 'jp', 'kr',
16    'nl', 'tr', 'pl', 'pt', 'lu', 'be', 'ru'
17  ];
18
19  window.ekooGetLocale = function() {
20    var lang = (document.documentElement.getAttribute('lang') || '').trim().toLowerCase();
21    if (!lang) return 'fr'; // default fallback
22
23    // Check full tag first (e.g., zh-hans)
24    if (mapping[lang]) return mapping[lang];
25
26    // Check primary subtag (e.g., fr from fr-FR)
27    var primary = lang.split('-')[0];
28    if (mapping[primary]) return mapping[primary];
29
30    // Direct match against Ekoo locales
31    if (ekooLocales.indexOf(primary) !== -1) return primary;
32
33    return 'fr'; // fallback
34  };
35})();
36</script>

Then use the helper function to set the locale dynamically:

Using the mapping

html

1<div
2  data-ekoo="YOUR_WEBSITE_ID"
3  data-ekoo-product-id="YOUR_PRODUCT_ID"
4></div>
5
6<script>
7  // After DOM is ready, set the locale from the mapping
8  var widget = document.querySelector('[data-ekoo]');
9  if (widget && window.ekooGetLocale) {
10    widget.setAttribute('data-ekoo-locale', window.ekooGetLocale());
11  }
12</script>

💡

Tag your audio content

Make sure your audio content in the backoffice is tagged with the correct locale. If you forget to tag audio, it won't appear when a locale filter is active.

ℹ️

UI language is not affected

The locale attribute only filters which audio is displayed — it does not translate the widget's UI elements.