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:
The end result is a multilingual site that displays translated content based on the visitor's language preferences.
Note: These steps translate content you render yourself. Wix-managed pages such as the login page and checkout use a separate mechanism. To learn more, see display Wix-managed pages in a specific language.
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:
Install the Wix Multilingual app on your site.
Set up your multilingual dashboard.
Install the @wix/essentials package:
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:
Create a file named translations.json in your src folder.
Add your translation keys and source text as key-value pairs:
You can also add a grouping level to organize related translation keys:
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:
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.
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:
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:
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.
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:
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:
Import i18n from the @wix/essentials package:
Initialize a translation helper function. The getTranslationFunction() method detects the site visitor's selected language and returns the appropriate translation.
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:
Full code example
Site visitors can now view your content in their preferred language.
The steps above translate content on your headless site. Wix-managed pages, such as the login page and checkout, use a separate mechanism.
When you redirect visitors to a Wix-managed page with Create Redirect Session, set the page language in preferences.additionalQueryParameters.lang using an ISO 639 language code. For example, pass "es" for Spanish or "fr" for French.
Alternatively, send the x-wix-linguist header on the Create Redirect Session request. If you don't set lang explicitly, Wix adds the header value to the redirect URL as lang. If you set both, lang takes priority.
This applies to any Wix-managed page you open through a redirect session, including the Wix login page.
Before you set the language, make sure the Wix Multilingual app is installed on a site and the target language is enabled in the Multilingual dashboard.
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.
Last updated: 30 August 2026