Motivation

Fix #4723

Fix #6462

Fix #6075 (comment)

Supersede #6731

This PR permits improving the i18n support for deploying an i18n site, in particular in more complex and multi-domain deployments.

We already had these:

• url: The url/domain of your site
• baseUrl: The baseUrl of your site's main locale, also used as a base for localized sites hosted under subpaths like /<baseUrl>/<locale>/

This introduces:

• i18n.localeConfigs[locale].url: The url/domain of your site for a given locale
• i18n.localeConfigs[locale].baseUrl: The baseUrl of your site for a given locale

Problems

Until now, Docusaurus had heuristics to automatically infer the "final baseUrl" of a localized site, based on the global siteConfig.baseUrl attribute:

• /<baseUrl>/ for the default locale
• /<baseUrl>/<locale>/ for other locales, hosted under subpaths
• /<baseUrl>/ for all locales when building a single locale at a time (docusaurus build --locale fr), assuming a multi-domain deployment.

This works well for most sites, but does not really give enough flexibility.

For example, what if you don't want your default locale to be hosted at the site root, but want a consistent /<locale>/ prefix?

Also the previous implementation was buggy for multi-domain setups because there was no way to tell Docusaurus what the domains are for each locale. These features didn't work well:

• The alternative URLs we navigate to when switching locale (in the navbar locale dropdown)
• The hreflang meta used for crawlers like Google to detect localized variants of a given page.

With the new options, it's possible to give more flexibility and pass a custom url / baseUrl for each locale, giving you the ability to override the default values based on siteConfig.url and siteConfig.baseUrl.

The existing heuristics have been kept as-is for retrocompatibility, but can now be overridden.

Test Plan

Unit tests

Many local tests

Using our current website config:

• ✅ yarn workspace website build: produces build and build/fr (+ other locales), can be served properly, has right canonical URL and hreflang meta
• ✅ yarn workspace website build --locale en --locale fr: same result
• ✅ yarn workspace website build --locale fr: builds/serve fine, outputs in build, has correct hreflang meta

Using a custom config on our website:

      localeConfigs: {
        en: {
          url: 'https://en.docusaurus.io',
          baseUrl: 'custom',
        },
        fr: {
          url: 'https://fr.docusaurus.io',
          baseUrl: 'whatever/else',
        },
      },

• ✅ yarn workspace website build: works well
• ✅ yarn workspace website build --locale en --locale fr: works well
• ✅ yarn workspace website build --locale fr: works well

Test links

Preview: https://deploy-preview-11316--docusaurus-2.netlify.app/

Docs:

• https://deploy-preview-11316--docusaurus-2.netlify.app/docs/api/docusaurus-config#url
• https://deploy-preview-11316--docusaurus-2.netlify.app/docs/api/docusaurus-config#baseUrl
• https://deploy-preview-11316--docusaurus-2.netlify.app/docs/api/docusaurus-config#i18n
• https://deploy-preview-11316--docusaurus-2.netlify.app/docs/i18n/tutorial#deploy-your-site

Related issues/PRs

Supersede #6731