> For the complete documentation index, see [llms.txt](https://lingojs.gitbook.io/lingojs-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lingojs.gitbook.io/lingojs-docs/language-and-widget.md).

# 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:

```js
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:

```html
<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:

```js
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:

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

Then enable inline mode when initializing the snippet:

```js
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:

```js
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:

```jsx
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.