Language & Widget

Configure the languages available for a project and control how visitors switch between them.

Project languages

The base language is the language already used by the website. Target languages are the translated versions offered to visitors.

Manage them from the project dashboard before initializing the snippet with matching language codes:

window.lingojs.initialize({
  projectKey: 'YOUR_PROJECT_KEY',
  baseLanguage: 'en',
  targetLanguage: 'fr'
});

targetLanguage can be changed when your application already controls language selection.

Automatic language selection

The snippet resolves the active language in this order:

1. a previously saved visitor choice, when rememberLanguage is enabled;

2. targetLanguage passed to initialize();

3. the x-lingo-lang meta tag;

4. baseLanguage.

When targetLanguage is omitted and no saved choice exists, you can provide the preferred language with a meta tag:

<meta name="x-lingo-lang" content="fr" />

Changing targetLanguage does not override an existing saved visitor choice while rememberLanguage remains enabled.

Language switcher

Enable the built-in switcher in the snippet configuration:

window.lingojs.initialize({
  projectKey: 'YOUR_PROJECT_KEY',
  baseLanguage: 'en',
  showWidget: true,
  rememberLanguage: true
});

• showWidget displays the language switcher.

• rememberLanguage saves the visitor's selection in the browser.

The widget appears when the project has at least two configured languages.

Embed the widget in your layout

By default, the switcher floats over the page. To place it inside a header, navigation bar, footer, or any other layout section, add a widget anchor:

<div data-lingojs-widget></div>

Then enable inline mode when initializing the snippet:

window.lingojs.initialize({
  projectKey: 'YOUR_PROJECT_KEY',
  baseLanguage: 'en',
  showWidget: true,
  widgetMode: 'inline'
});

The switcher is inserted inside the first matching anchor and follows the normal layout instead of using a fixed screen position. If the anchor is rendered later or replaced by a React, Next.js, or page-builder update, the snippet automatically mounts the widget again.

Inline mode stays hidden while no anchor is available. You can customize the anchor selector or explicitly restore the floating widget as a fallback:

window.lingojs.initialize({
  projectKey: 'YOUR_PROJECT_KEY',
  baseLanguage: 'en',
  showWidget: true,
  widgetMode: 'inline',
  widgetSelector: '#language-switcher',
  widgetFallback: 'floating'
});

For React or Next.js, render the anchor as part of your component or layout:

export function LanguageSwitcher() {
  return <div data-lingojs-widget />;
}

WordPress and Elementor

With the official LingoJS WordPress plugin:

1. Open Settings > LingoJS.

2. Set Widget Display to Embedded in page.

3. Add the [lingojs_widget] shortcode where the switcher should appear.

In Elementor, use a Shortcode widget and enter [lingojs_widget]. The same shortcode works with Gutenberg and other page builders that support WordPress shortcodes.

Customize the widget

Open Dashboard > Project > Widget to configure:

• background, text, and button colors;

• preset or custom positioning;

• font family, size, and weight;

• border radius, menu radius, and shadow.

Click Save Configuration, then reload the website to verify the result.

Position presets apply to floating mode. In inline mode, the anchor's parent layout controls where the switcher appears.

Translated content

In addition to visible text nodes, the snippet translates supported values in placeholder, title, alt, and aria-label attributes.

Automatic hreflang links

If the page does not already contain any <link hreflang> element, the snippet adds alternate-language links for the configured project languages and an x-default link. Configure the project's base URL correctly if you rely on these generated SEO links. If your site already manages hreflang links, the snippet leaves them unchanged.