Add Multilingual Support

You can support multiple languages in your Wix-managed headless project with the @wix/essentials package, which uses static content translations. Use the Wix CLI to sync translation keys between your local codebase and the Multilingual dashboard, and use getTranslationFunction() from @wix/essentials to retrieve translated values in your code. This way, content editors can manage translations without modifying your code.

To add multilingual support to your headless site:

  1. Set up the Wix Headless environment.
  2. Define your source translations.
  3. Push translation keys to the dashboard.
  4. Add translations on the dashboard.
  5. Pull translations to the site.
  6. Use translations in your code.

The end result is a multilingual site that displays translated content based on the visitor's language preferences.

Step 1 | Set up the Wix Headless environment

This step sets up a Wix Headless site with the necessary apps and packages for multilingual support.

At the end of this step, you have a Wix Headless site with the Wix Multilingual app installed and the @wix/essentials package ready to use.

To set up the Wix Headless environment:

  1. Create a Wix Headless site.

  2. Install the Wix Multilingual app on your site.

  3. Set up your multilingual dashboard.

  4. Install the @wix/essentials package:

    Copy

Step 2 | Define your source translations

This step creates a JSON file where you define key-value pairs for your translations. The key is the translation key you use in your code to display translated text. The value is the text in the site's main language.

At the end of this step, you have a translations.json file with your translation keys and source text.

To define your source translations:

  1. Create a file named translations.json in your src folder.

  2. Add your translation keys and source text as key-value pairs:

    Copy

You can also add a grouping level to organize related translation keys:

Copy

Step 3 | Push translation keys to the dashboard

This step uploads your translation keys to the Multilingual dashboard so content editors can add translations.

At the end of this step, your translation keys appear on the dashboard ready for translation.

To push translation keys to the dashboard, run the following command:

Copy

This command uploads the translation keys defined in src/translations.json, such as checkout or hero.title. The keys now appear in the Multilingual dashboard, where editors can add languages and input translations.

Step 4 | Add translations to the dashboard

This step adds translations for each language you want to support in the dashboard.

At the end of this step, your translations are stored on the dashboard and ready to pull into your project.

To add translations on the dashboard:

  1. In the dashboard menu, click Website Content, then Multilingual.
  2. Add the languages you want to support.
  3. Hover over the language section and click Edit Translations.
  4. In the Translation Manager, click Headless.
  5. Add translations.
  6. Click Save and Publish.

Step 5 | Pull translations from the dashboard

This step fetches the translations from the dashboard so you can use them in your app.

At the end of this step, you have JSON files for each language stored locally in your project.

To pull translations, run the following command:

Copy

This command connects to the Wix Multilingual backend, downloads translation files for all enabled languages, and stores them in the .wix/multilingual folder.

Because every Wix Headless scaffold gitignores .wix/ by default, .wix/multilingual isn't committed to your repository. When you enable translations, run npm run wix translation pull in every clean clone and CI environment before building. Otherwise, astro build and astro dev fail at startup.

Step 6 | Modify astro.config.mjs

Use Wix Multilingual, not Astro's i18n routing, for locale routing. Wix's localization middleware strips the locale segment before Astro matches folder-based i18n routes, and @wix/astro-pages registers page entries from each route folder. Keep src/pages flat and use i18n.getLanguage() from @wix/essentials to read the current locale instead of Astro's currentLocale.

In your astro.config.mjs file, update the wix object by adding essentials: true and translations: true:

Copy

Step 7 | Use translations in your code

This step shows how to display translated content in your app using the getTranslationFunction() method.

At the end of this step, your app displays content in the visitor's preferred language.

To use translations in your code:

  1. Import i18n from the @wix/essentials package:

    Copy

  2. Initialize a translation helper function. The getTranslationFunction() method detects the site visitor's selected language and returns the appropriate translation.

    Copy

  3. In your page component file, call useTranslation() to get the translation function, and then get the translated text using a key path from your translations.json file:

    Copy

Full code example

Copy

Site visitors can now view your content in their preferred language.

SEO for secondary-language main pages

This article covers translating the content you render yourself. It doesn't cover SEO tags, such as titles and meta descriptions, which Wix manages separately for main pages. Main-page SEO isn't currently language-specific: see Manage SEO for Main Pages: Multilingual sites before relying on a secondary-language route's SEO tags.

See also

Last updated: 12 August 2026

Did this help?