Headless Wix internationalisation and multi-region SEO

Headless Wix gives you complete control over hreflang implementation, multi-region URL structures, international content serving, and language-specific sitemap generation — all areas where the standard Wix platform imposes constraints that can limit your international SEO performance. The Wix Multilingual feature stores translated content that you access via the API, and the headless frontend determines exactly how that content is routed, rendered, and signalled to Google. This lesson covers how to build a properly internationalised headless Wix site that ranks in multiple countries and languages, from initial URL structure decisions through to automated hreflang generation, sitemap internationalisation, and content quality validation workflows.

URL Structures for International Headless Sites

The first architectural decision for an international headless Wix site is your URL structure. Your three options are subdirectories (/en/, /fr/, /de/), subdomains (fr.example.com), or separate domains (example.fr). Wix uses the subdirectory structure for its own multilingual feature, and it is the approach most recommended by Google for sites that want to consolidate domain authority while supporting multiple languages. Subdirectories are also the easiest to implement with Next.js built-in internationalisation features, which handle locale detection and routing automatically.

Subdomain and separate domain structures can be appropriate for very large international operations where regional sites need independent content strategies, but they require separate domain authority building for each language version and add complexity to hreflang implementation. For most headless Wix sites targeting 2-10 language markets, the subdirectory approach (/fr/, /de/, /es/) is the right choice and aligns with how Wix Multilingual organises translated content in the CMS.

Configuring Next.js internationalisation for subdirectory URL routing

• In next.config.js, add the i18n configuration object with your locales array and defaultLocale: module.exports = { i18n: { locales: ["en", "fr", "de", "es"], defaultLocale: "en" } }
• Next.js automatically routes /fr/[path] to the fr locale and /en/[path] to the en locale — the default locale (en) also serves at the root URL (/) without a language prefix
• In your page components, access the current locale using useRouter().locale on the client or through the params prop on server components in the App Router
• When making Wix API calls, pass the locale parameter to fetch the appropriate language version: wixClient.blog.listPosts({ language: locale })
• Create a middleware.ts file at the project root to handle automatic locale detection based on the Accept-Language request header for first-time visitors
• In middleware, check if the incoming URL already has a locale prefix — if not, detect the preferred language from Accept-Language and redirect to the appropriate locale URL
• Add a language switcher component to your navigation that generates links to the equivalent page in each available language, using Next.js Link with the locale prop
• Set hreflang link tags in the document head for every page — Next.js does not generate these automatically, so you must add them in your layout or page metadata
• Test your routing by visiting /fr/, /de/, and /es/ URLs in your browser to confirm each language version loads the correct translated content from the Wix Multilingual API
• Verify that Google Search Console correctly identifies and crawls all language variants by checking the Coverage report after adding your international sitemaps

Hreflang Implementation at Scale

Every page version needs hreflang link tags in the head pointing to all other language and region versions of that same page. For a site with 5 languages and 200 pages, that is 1,000 individual hreflang relationships that must all be correct and bidirectional — each language version must link to all others, and the links must form a complete cluster. A missing or incorrect hreflang tag causes Google to potentially show the wrong language version to users in the wrong region, undermining your entire international SEO strategy.

With headless Wix, generate hreflang tags dynamically by querying the Wix Multilingual API to identify which translations exist for each page. Not all pages may be translated into all languages, so you should only include hreflang tags for language versions that actually exist with complete translated content. Always include an x-default hreflang pointing to your primary language version for users whose language or region is not specifically targeted.

Generating dynamic hreflang tags from Wix Multilingual data

• Create a lib/hreflang.ts utility that accepts a page path and returns an array of hreflang link tag objects: [{ hreflang: "fr", href: "https://example.com/fr/[path]" }, ...]
• Query the Wix Multilingual API to get the list of available translations for each page — only generate hreflang tags for languages that have a complete translation, not for machine-translated drafts
• Always include the x-default hreflang entry pointing to your default language URL: { hreflang: "x-default", href: "https://example.com/[path]" }
• Use BCP 47 language codes in hreflang: "en" for English (all regions), "en-GB" for UK-specific English, "fr" for French, "de" for German — match the format to your targeting specificity
• In your Next.js layout or page metadata, use the alternates.languages property in the generateMetadata function to output hreflang link tags: alternates: { languages: { fr: "/fr/[path]", de: "/de/[path]" } }
• Verify bidirectionality: if your French page (/fr/about) includes hreflang pointing to /de/about, then /de/about must also include hreflang pointing back to /fr/about — generate all language versions together to ensure this
• For region-specific targeting (en-US vs en-GB), use country-code suffixed locale codes in your Next.js i18n config and Wix API calls
• Test your hreflang implementation using the Ahrefs Site Audit hreflang report or the Merkle hreflang tag testing tool — paste your page URL and check for orphaned tags or missing return links
• Add hreflang tags to your XML sitemaps as an alternative to head tags — use the <xhtml:link> element inside each <url> block listing all language variants
• Monitor Google Search Console for hreflang errors under International Targeting — common errors include missing return tags and conflicting canonical/hreflang signals

Content Localisation from Wix Multilingual

The Wix Multilingual feature stores translated content alongside the original in the Wix CMS, and you access language-specific content through the Wix API by passing a language parameter with your API requests. The API returns the appropriate translation based on the requested language code, falling back to the primary language if a translation is not available. Your headless frontend should handle this fallback gracefully — either rendering the primary language content with a visible "translation coming soon" notice, or excluding that page from the sitemap and hreflang cluster until a complete translation exists.

• Always pass the locale parameter to every Wix API call that returns user-facing content: posts, pages, products, categories, and navigation items all need language-specific versions
• Store locale-specific SEO metadata (meta title, meta description, Open Graph title) in Wix Multilingual fields and retrieve them in your generateMetadata function
• Generate locale-specific canonical URLs that use the language prefix: canonical for the French version is /fr/[path], not the English /[path]
• Translate URL slugs where culturally appropriate — a French URL of /fr/a-propos is more authentic than /fr/about and signals localisation depth to Google
• Include locale-specific structured data: LocalBusiness schema should include address and phone number in the local format, and Article schema should set inLanguage to the correct language code
• Store translated image alt text in Wix Multilingual fields so your French pages have French alt text on images, not English alt text on a French page
• Ensure your XML sitemaps include locale-specific URLs with the correct lastmod date for each language version independently — different languages may have different translation dates
• Use locale-appropriate date and number formatting in your rendered content — French users expect "22 avril 2026" not "April 22, 2026"

International Sitemap Strategy

For international headless Wix sites, your sitemap strategy needs to clearly signal to Google which pages exist in which language, and how they relate to each other. There are two accepted approaches: including hreflang annotations inside a single unified sitemap using the xhtml:link element, or generating separate per-language sitemaps (sitemap-en.xml, sitemap-fr.xml) listed in a sitemap index file. The per-language approach is easier to maintain as your content grows and makes it straightforward to see at a glance which language has the most indexed content.

Building per-language sitemaps for an international headless Wix site

• Create a sitemap index file at /sitemap.xml that lists individual sitemaps: sitemap-en.xml, sitemap-fr.xml, sitemap-de.xml with their lastmod dates
• Create a dynamic route at app/sitemap-[locale].xml/route.ts that accepts a locale parameter and generates a sitemap for that language using Wix API data
• For each locale sitemap, query all translated content from the Wix API using the locale parameter and include only pages where a complete translation exists
• Format each URL entry with the full absolute URL including the locale prefix: https://example.com/fr/[path] for French pages
• Include the lastmod field for each URL using the most recent translation update date from the Wix Multilingual API, not the original English post date
• Add xhtml:link alternate entries inside each URL block listing all other language versions of that page — this is optional but recommended by Google as belt-and-suspenders with head hreflang tags
• Submit your sitemap index file (not individual sitemaps) to Google Search Console — GSC will discover and crawl all referenced sitemaps automatically
• Also submit to Bing Webmaster Tools if you target markets where Bing has significant share (US, UK, Canada)
• Verify sitemap discovery by checking the Sitemaps report in Google Search Console one week after submission — confirm each language sitemap is discovered and shows a URL count matching your actual published content
• Set up a monthly check comparing your sitemap URL count to your actual published page count — discrepancies indicate pages being excluded from the sitemap that should be included