@bablic-io/selector

Build your own language selector for a website translated with Bablic.

It provides two functions:

• getLanguages() returns your project's languages and tells you which one the visitor is viewing.
• setLanguage(value) switches the visitor to another language, using the same mechanism as Bablic's built-in selector (cookie, URL parameter, folder, domain, or browser storage, depending on your project's setup).

You build the selector UI however you like.

The library has no dependencies, is about 7 kB minified, and makes one small request per page.

You still need the Bablic script. This library only lists the languages and switches between them. Bablic's translation script, the snippet from your Bablic dashboard, is what actually translates the page. Keep it on your site: without it, setLanguage() still switches the language, but the page stays untranslated. The selector works independently of the Bablic script, so you can load the two in any order.

Option 1: script tag

Add the script with your project key, then build your selector:

<script src="https://edge.bablic.com/selector.min.js" data-bablic="YOUR_PROJECT_KEY"></script>

<select id="language-selector"></select>

<script>
  const select = document.getElementById('language-selector');

  BablicSelector.getLanguages().then((languages) => {
    languages.forEach(({ value, label, isCurrent }) => {
      const option = document.createElement('option');
      option.value = value;
      option.textContent = label;
      option.selected = isCurrent;
      select.appendChild(option);
    });
  });

  select.addEventListener('change', (e) => {
    BablicSelector.setLanguage(e.target.value);
  });
</script>

Where to put the script tag:

• Before your own code: selector.min.js must come before any script that uses BablicSelector. We recommend putting it in the <head>.
• No async: with async, your code may run before BablicSelector exists. defer works only if the code that uses BablicSelector is deferred too, or waits for DOMContentLoaded.
• type="text/javascript" is optional: browsers treat scripts as JavaScript by default. It does no harm if your CMS adds it.

Option 2: npm package

npm install @bablic-io/selector

import { useEffect, useState } from 'react';
import { getLanguages, setLanguage } from '@bablic-io/selector';

const PROJECT_KEY = 'YOUR_PROJECT_KEY';

function LanguageSelector() {
  const [languages, setLanguages] = useState([]);

  useEffect(() => {
    getLanguages(PROJECT_KEY).then(setLanguages);
  }, []);

  const current = languages.find((language) => language.isCurrent);

  return (
    <select value={current?.value} onChange={(e) => setLanguage(e.target.value)}>
      {languages.map(({ value, label }) => (
        <option key={value} value={value}>{label}</option>
      ))}
    </select>
  );
}

The package is safe to import during server-side rendering. Call getLanguages() in the browser only, for example inside useEffect.

API

getLanguages(projectKey, options?) → Promise<Language[]>

• projectKey: your Bablic project key. With the script tag, it comes from data-bablic, so BablicSelector.getLanguages() takes no arguments.
• options.host: the Bablic server to use. The default is https://edge.bablic.com/. With the script tag, it is the server selector.min.js was loaded from.

Each language is:

| Field | Type | Description | |-------------|-----------|-------------| | value | string | Identifies the language. Pass it to setLanguage(). | | label | string | Display name: your custom label, or the language's native name. | | langCode | string | Language code, e.g. FR-FR. | | isDefault | boolean | true for your site's original language. | | isCurrent | boolean | true for the language the visitor is viewing. |

• Order: languages are sorted by label.
• Single request: the languages are loaded once per page; later calls reuse them.
• Empty list: the promise resolves to [] (and logs a warning) when the project isn't available: it isn't published yet, translations are turned off, or your site's domain isn't allowed for the project.
• Errors: the promise rejects only on network or server errors.

NOTE: You can edit value and label using the Bablic dashboard app at https://dashboard.bablic.com/ .

setLanguage(value)

Switches the visitor to the language with this value. value must be one of the values returned by getLanguages(). Depending on your project's setup, it does one of the following:

• Cookie: sets the language cookie and reloads the page.
• URL parameter: updates the language parameter in the address and navigates.
• Folder: replaces the language folder in the path (e.g. /fr/page → /de/page) and navigates.
• Domain: moves to the language's domain, keeping the same page.
• Browser storage: stores the language and reloads the page.

Previewing languages that aren't live yet

Open your page with ?bablic_preview=1. getLanguages() then also returns languages that are still in preview, and works on projects that aren't published yet.