How to add a language switcher

In TeleportHQ, a language switcher lets visitors choose the language of your site. When you add a language, TeleportHQ can place one in your navigation and footer for you. To add one yourself, open Elements → Primitives, find the Interactive group, and add lang-switcher, a dropdown that lists your languages, or Lang Toggle, an inline row such as "en / es" that highlights the active language. Both list your site's languages automatically, and neither turns your website into a web app.

Before you start#

• Your site needs at least two languages, or the switcher shows only one option. See How to add a language.
• On a TeleportHQ free trial, you can't add a second language, because language slots can only be bought on Pro or Premium. See How to make your site available in several languages.
• Put the switcher in your navigation or footer component, so it appears on every page. See How to mark a component as your navigation, footer or logo.
• A language switcher works on any website. It doesn't make your website a web app and needs no advanced feature. See What's the difference between a website and a web app?
• You need a role that can add elements to the project.

Steps#

Let TeleportHQ add it when you add a language#

1. Add a language from the language button at the top left of the canvas. See How to add a language.
2. In the Add Spanish inside the project window, leave Add a language switcher to the navigation and footer on.

3. Click Add Spanish.

TeleportHQ uses AI to decide where the switcher fits in your navigation and footer, and picks a dropdown or an inline toggle such as "EN / ES" to suit the space. The Language switcher step of the progress window then says "Added to your navigation and footer — restyle it from the canvas".

The switch only shows when your navigation or footer is finished and has no language switcher yet, and your workspace has enough AI tokens.

Add a dropdown switcher (lang-switcher)#

1. Open your navigation component, and select the element the switcher goes in, for example the row of menu links.
2. In the left sidebar, click Elements, then the Primitives tab.
3. In the Interactive group, find the two language switchers:
   1. lang-switcher: a dropdown that lists your languages.
   2. Lang Toggle: an inline row of language codes.

4. Click lang-switcher to add it inside the selected element, or drag it into place.
5. Style it in the right panel. In the layers tree it shows as Lang Switcher, with a Dropdown Toggle (what visitors click) and a Dropdown List (the languages).

Add an inline switcher (Lang Toggle)#

1. Open your navigation or footer component, and select the element the switcher goes in.
2. In Elements → Primitives → Interactive, click Lang Toggle, or drag it into place.
3. Style the language codes and the / separator in the right panel. The active language is highlighted on its own.

Check that it worked#

1. In the floating toolbar at the bottom center of the editor, click Preview. The preview opens in the language you're editing.
2. Click the switcher and pick another language. The page changes to that language.

On your live site, the switcher works after you publish. See How URLs and SEO work on a multilingual site.

Troubleshooting#

"Add a second language under Internationalization for the switcher to list more than one option." Your site has only one language, so the switcher has nothing to switch to. Add a language first.

The switcher only shows one language Same cause: add another language. The switcher updates on its own when you add or remove languages.

The progress window says "Not enough tokens to place it — add a Lang Switcher from the Elements panel when you are ready." Your workspace ran out of AI tokens before the switcher was placed. Add lang-switcher or Lang Toggle yourself, as described above.

The progress window says "The switcher could not be added to your footer — add a Lang Switcher from the Elements panel." TeleportHQ couldn't find a place for it. Add it yourself in that component.

The Add a language switcher switch doesn't show when I add a language Your navigation and footer already have a language switcher, aren't finished yet, or your workspace is low on AI tokens.

Good to know#

• To show a flag next to each language in the dropdown, add the flag images inside the switcher's LanguageLink (so they're part of the link) and show one per language with a condition on the item's language code: the switcher's allLanguages context, short is en for one image, es for the other. For the closed toggle, use the current language's short. See How to show or hide elements based on a condition.
• Lang Toggle marks the active language with a data-active-locale attribute, which developers can use for custom styling.
• When Ignore browser language is off, visitors first land on the language that matches their browser. The switcher lets them change it.
• Downloaded code: a Next.js download keeps the switcher working. An HTML download holds one language, so a switcher has nothing to switch to. When your site uses Lang Toggle, the download window names Language Switcher among the widgets that only work in the Next.js export.