feat: add support for multi domain locales (#3065)

Co-authored-by: Vincent de Vreede <vincentdevreede@live.nl> Co-authored-by: DarthGigi <47110839+DarthGigi@users.noreply.github.com>
nuxt-modules · Aug 19, 2024 · 8891600 · 8891600
1 parent fe262c4
commit 8891600
Show file tree

Hide file tree

Showing 51 changed files with 1,809 additions and 1,769 deletions.
diff --git a/docs/content/docs/2.guide/10.multi-domain-locales.md b/docs/content/docs/2.guide/10.multi-domain-locales.md
@@ -0,0 +1,170 @@
+---
+title: Multi domain locales
+description: Set up multiple domains for multiple locales. Use a different domain name for each language your app supports.
+---
+
+How to set up multi domain locales:
+
+- Set the `multiDomainLocales` option to `true`
+- Configure the `locales` option as an array of objects:
+  - Each object has a `domains` key whose value is a array of the domains you'd like to use for that locale. Optionally include a port (if non-standard) and/or a protocol. If the protocol is not provided then an attempt will be made to auto-detect it but that might not work correctly in some cases like when the pages are statically generated.
+  - Optionally set for each object a `defaultForDomains` key whose value is a array of the default domains you'd like to use for that locale. Optionally include a port (if non-standard) and/or a protocol. If the protocol is not provided then an attempt will be made to auto-detect it but that might not work correctly in some cases like when the pages are statically generated.
+- Optionally set `detectBrowserLanguage` to `false`. When enabled (which it is by default), user can get redirected to a different domain on first visit. Set to `false` if you want to ensure that visiting given domain always shows page in the corresponding locale.
+
+```ts [nuxt.config.ts]
+const i18nDomains = ['mydomain.com', 'es.mydomain.com', 'fr.mydomain.com', 'http://pl.mydomain.com', 'https://ua.mydomain.com']
+
+export default defineNuxtConfig({
+  i18n: {
+    locales: [
+      {
+        code: 'en',
+        domains: i18nDomains,
+        defaultForDomains: ['mydomain.com']
+      },
+      {
+        code: 'es',
+        domains: i18nDomains,
+        defaultForDomains: ['es.mydomain.com']
+      },
+      {
+        code: 'fr',
+        domains: i18nDomains,
+        defaultForDomains: ['fr.mydomain.com']
+      },
+      {
+        code: 'pl',
+        domains: i18nDomains,
+        defaultForDomains: ['http://pl.mydomain.com']
+      },
+      {
+        code: 'ua',
+        domains: i18nDomains,
+        defaultForDomains: ['https://ua.mydomain.com']
+      },
+      {
+        code: 'nl',
+        domains: i18nDomains
+      },
+      {
+        code: 'de',
+        domains: i18nDomains
+      },
+    ],
+    multiDomainLocales: true
+  }
+})
+```
+
+## Runtime environment variables
+
+Sometimes there's a need to change domains in different environments, e.g. staging and production.
+As `nuxt.config.ts` is used at build time it would be necessary to create different builds for different environments.
+
+```ts [locale-domains.config.ts]
+export const localeDomains = {
+  uk: process.env.DOMAIN_UK,
+  fr: process.env.DOMAIN_FR
+}
+```
+
+```ts [nuxt.config.ts]
+import { localeDomains } from './locale-domains.config'
+
+const i18nDomains = [localeDomains.uk, localeDomains.fr]
+
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/i18n'],
+
+  i18n: {
+    multiDomainLocales: true,
+    locales: [
+      {
+        code: 'uk',
+        domains: i18nDomains,
+        defaultForDomains: [localeDomains.uk]
+      },
+      {
+        code: 'fr',
+        domains: i18nDomains,
+        defaultForDomains: [localeDomains.fr]
+      }
+    ]
+  }
+})
+```
+
+With the above config, a build would have to be run for staging and production with different .env files that specify `DOMAIN_UK` and `DOMAIN_FR`.
+
+## Using different domains for only some of the languages
+
+If one or more of the domains need to host multiple languages, the default language of each domain needs to have `domainDefault: true` so there is a per domain fallback locale.
+The option `differentDomains` still need to be set to `true` though.
+
+```js {}[nuxt.config.js]
+const i18nDomains = ['mydomain.com', 'en.mydomain.com', 'es.mydomain.com', 'fr.mydomain.com', 'http://pl.mydomain.com', 'https://ua.mydomain.com']
+
+export default defineNuxtConfig({
+  // ...
+  i18n: {
+    locales: [
+      {
+        code: 'en',
+        domains: i18nDomains,
+        defaultForDomains: ['mydomain.com', 'en.mydomain.com']
+      },
+      {
+        code: 'es',
+        domains: i18nDomains,
+        defaultForDomains: ['es.mydomain.com']
+      },
+      {
+        code: 'fr',
+        domains: i18nDomains,
+        defaultForDomains: ['fr.mydomain.com']
+      },
+      {
+        code: 'pl',
+        domains: i18nDomains,
+        defaultForDomains: ['http://pl.mydomain.com']
+      },
+      {
+        code: 'ua',
+        domains: i18nDomains,
+        defaultForDomains: ['https://ua.mydomain.com']
+      },
+      {
+        code: 'nl',
+        domains: i18nDomains
+      },
+      {
+        code: 'de',
+        domains: i18nDomains
+      },
+    ],
+    strategy: 'prefix',
+    multiDomainLocales: true
+  },
+  // ...
+})
+```
+
+Given above configuration with the `prefix` strategy, following requests will be:
+- https://mydomain.com -> https://mydomain.com/en (en language)
+- https://mydomain.com/pl -> https://mydomain.com/pl (pl language)
+- https://mydomain.com/ua -> https://mydomain.com/ua (ua language)
+- https://mydomain.com/nl -> https://mydomain.com/nl (nl language)
+- https://en.mydomain.com -> https://en.mydomain.com/en (en language)
+- https://es.mydomain.com -> https://es.mydomain.com/es (es language)
+- https://fr.mydomain.com -> https://fr.mydomain.com/fr (fr language)
+- https://fr.mydomain.com/de -> https://fr.mydomain.com/de (de language)
+
+The same requests when using the `prefix_except_default` strategy, will be:
+- https://mydomain.com -> https://mydomain.com (en language)
+- https://mydomain.com/pl -> https://mydomain.com/pl (pl language)
+- https://mydomain.com/ua -> https://mydomain.com/ua (ua language)
+- https://mydomain.com/nl -> https://mydomain.com/nl (nl language)
+- https://en.mydomain.com -> https://en.mydomain.com (en language)
+- https://es.mydomain.com -> https://es.mydomain.com (es language)
+- https://fr.mydomain.com -> https://fr.mydomain.com (fr language)
+- https://fr.mydomain.com/de -> https://fr.mydomain.com/de (de language)
diff --git a/...ontent/docs/2.guide/10.locale-fallback.md → ...ontent/docs/2.guide/11.locale-fallback.md b/...ontent/docs/2.guide/10.locale-fallback.md → ...ontent/docs/2.guide/11.locale-fallback.md
diff --git a/.../2.guide/11.per-component-translations.md → .../2.guide/12.per-component-translations.md b/.../2.guide/11.per-component-translations.md → .../2.guide/12.per-component-translations.md
diff --git a/...ontent/docs/2.guide/12.extend-messages.md → ...ontent/docs/2.guide/13.extend-messages.md b/...ontent/docs/2.guide/12.extend-messages.md → ...ontent/docs/2.guide/13.extend-messages.md
diff --git a/docs/content/docs/2.guide/13.extend-pages.md → docs/content/docs/2.guide/14.extend-pages.md b/docs/content/docs/2.guide/13.extend-pages.md → docs/content/docs/2.guide/14.extend-pages.md
diff --git a/docs/content/docs/2.guide/14.layers.md → docs/content/docs/2.guide/15.layers.md b/docs/content/docs/2.guide/14.layers.md → docs/content/docs/2.guide/15.layers.md
diff --git a/...cs/2.guide/15.server-side-translations.md → ...cs/2.guide/16.server-side-translations.md b/...cs/2.guide/15.server-side-translations.md → ...cs/2.guide/16.server-side-translations.md
diff --git a/...content/docs/2.guide/16.install-module.md → ...content/docs/2.guide/17.install-module.md b/...content/docs/2.guide/16.install-module.md → ...content/docs/2.guide/17.install-module.md
diff --git a/docs/content/docs/2.guide/17.migrating.md → docs/content/docs/2.guide/18.migrating.md b/docs/content/docs/2.guide/17.migrating.md → docs/content/docs/2.guide/18.migrating.md
diff --git a/docs/content/docs/3.options/2.routing.md b/docs/content/docs/3.options/2.routing.md
@@ -45,6 +45,8 @@ When using an object form, the properties can be:
 - `dir` - The dir property specifies the direction of the elements and content, value could be `'rtl'`, `'ltr'` or `'auto'`.
 - `domain` (required when using [`differentDomains`](/docs/options/domain#differentdomains)) - the domain name you'd like to use for that locale (including the port if used). This property can also be set using [`runtimeConfig`](/docs/options/runtime-config).
 - `domainDefault` (required when using [`differentDomains`](/docs/options/domain#differentdomains) while one or more of the domains having multiple locales) - set `domainDefault` to `true` for each locale that should act as a default locale for the particular domain.
+- `domains` (required when using [`multiDomainLocales`](/docs/options/domain#multiDomainLocales) while one or more of the domains having multiple of the same locales) - an array of [`domain`].
+- `defaultForDomains` (optional when using [`multiDomainLocales`](/docs/options/domain#multiDomainLocales)) - an array of [`domain`] for which the locale should be the default locale when using [`domains`].
 - `...` - any custom property set on the object will be exposed at runtime. This can be used, for example, to define the language name for the purpose of using it in a language selector on the page.
 
 You can access all the properties of the current locale through the `localeProperties` property. When using an array of codes, it will only include the `code` property.

diff --git a/docs/content/docs/3.options/5.domain.md b/docs/content/docs/3.options/5.domain.md
@@ -9,3 +9,10 @@ description: Browser locale management options.
 - default: `false`
 
 Set this to `true` when using different domains for each locale, with this enabled you MUST configure locales as an array of objects, each containing a `domain` key. Refer to the [Different domains](/docs/guide/different-domains) for more information.
+
+## `multiDomainLocales`
+
+- type: `boolean`
+- default: `false`
+
+Set this to `true` when using different domains with different locales. If enabled, you MUST configure locales as an array of objects, each containing a `domains` and `defaultForDomains` key. Refer to the [Multi Domain Locales](/docs/guide/multi-domain-locales) for more information.
diff --git a/docs/content/docs/5.v9/2.guide/10.multi-domain-locales.md b/docs/content/docs/5.v9/2.guide/10.multi-domain-locales.md
@@ -0,0 +1,170 @@
+---
+title: Multi domain locales
+description: Set up multiple domains for multiple locales. Use a different domain name for each language your app supports.
+---
+
+How to set up multi domain locales:
+
+- Set the `multiDomainLocales` option to `true`
+- Configure the `locales` option as an array of objects:
+  - Each object has a `domains` key whose value is a array of the domains you'd like to use for that locale. Optionally include a port (if non-standard) and/or a protocol. If the protocol is not provided then an attempt will be made to auto-detect it but that might not work correctly in some cases like when the pages are statically generated.
+  - Optionally set for each object a `defaultForDomains` key whose value is a array of the default domains you'd like to use for that locale. Optionally include a port (if non-standard) and/or a protocol. If the protocol is not provided then an attempt will be made to auto-detect it but that might not work correctly in some cases like when the pages are statically generated.
+- Optionally set `detectBrowserLanguage` to `false`. When enabled (which it is by default), user can get redirected to a different domain on first visit. Set to `false` if you want to ensure that visiting given domain always shows page in the corresponding locale.
+
+```ts [nuxt.config.ts]
+const i18nDomains = ['mydomain.com', 'es.mydomain.com', 'fr.mydomain.com', 'http://pl.mydomain.com', 'https://ua.mydomain.com']
+
+export default defineNuxtConfig({
+  i18n: {
+    locales: [
+      {
+        code: 'en',
+        domains: i18nDomains,
+        defaultForDomains: ['mydomain.com']
+      },
+      {
+        code: 'es',
+        domains: i18nDomains,
+        defaultForDomains: ['es.mydomain.com']
+      },
+      {
+        code: 'fr',
+        domains: i18nDomains,
+        defaultForDomains: ['fr.mydomain.com']
+      },
+      {
+        code: 'pl',
+        domains: i18nDomains,
+        defaultForDomains: ['http://pl.mydomain.com']
+      },
+      {
+        code: 'ua',
+        domains: i18nDomains,
+        defaultForDomains: ['https://ua.mydomain.com']
+      },
+      {
+        code: 'nl',
+        domains: i18nDomains
+      },
+      {
+        code: 'de',
+        domains: i18nDomains
+      },
+    ],
+    multiDomainLocales: true
+  }
+})
+```
+
+## Runtime environment variables
+
+Sometimes there's a need to change domains in different environments, e.g. staging and production.
+As `nuxt.config.ts` is used at build time it would be necessary to create different builds for different environments.
+
+```ts [locale-domains.config.ts]
+export const localeDomains = {
+  uk: process.env.DOMAIN_UK,
+  fr: process.env.DOMAIN_FR
+}
+```
+
+```ts [nuxt.config.ts]
+import { localeDomains } from './locale-domains.config'
+
+const i18nDomains = [localeDomains.uk, localeDomains.fr]
+
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/i18n'],
+
+  i18n: {
+    multiDomainLocales: true,
+    locales: [
+      {
+        code: 'uk',
+        domains: i18nDomains,
+        defaultForDomains: [localeDomains.uk]
+      },
+      {
+        code: 'fr',
+        domains: i18nDomains,
+        defaultForDomains: [localeDomains.fr]
+      }
+    ]
+  }
+})
+```
+
+With the above config, a build would have to be run for staging and production with different .env files that specify `DOMAIN_UK` and `DOMAIN_FR`.
+
+## Using different domains for only some of the languages
+
+If one or more of the domains need to host multiple languages, the default language of each domain needs to have `domainDefault: true` so there is a per domain fallback locale.
+The option `differentDomains` still need to be set to `true` though.
+
+```js {}[nuxt.config.js]
+const i18nDomains = ['mydomain.com', 'en.mydomain.com', 'es.mydomain.com', 'fr.mydomain.com', 'http://pl.mydomain.com', 'https://ua.mydomain.com']
+
+export default defineNuxtConfig({
+  // ...
+  i18n: {
+    locales: [
+      {
+        code: 'en',
+        domains: i18nDomains,
+        defaultForDomains: ['mydomain.com', 'en.mydomain.com']
+      },
+      {
+        code: 'es',
+        domains: i18nDomains,
+        defaultForDomains: ['es.mydomain.com']
+      },
+      {
+        code: 'fr',
+        domains: i18nDomains,
+        defaultForDomains: ['fr.mydomain.com']
+      },
+      {
+        code: 'pl',
+        domains: i18nDomains,
+        defaultForDomains: ['http://pl.mydomain.com']
+      },
+      {
+        code: 'ua',
+        domains: i18nDomains,
+        defaultForDomains: ['https://ua.mydomain.com']
+      },
+      {
+        code: 'nl',
+        domains: i18nDomains
+      },
+      {
+        code: 'de',
+        domains: i18nDomains
+      },
+    ],
+    strategy: 'prefix',
+    multiDomainLocales: true
+  },
+  // ...
+})
+```
+
+Given above configuration with the `prefix` strategy, following requests will be:
+- https://mydomain.com -> https://mydomain.com/en (en language)
+- https://mydomain.com/pl -> https://mydomain.com/pl (pl language)
+- https://mydomain.com/ua -> https://mydomain.com/ua (ua language)
+- https://mydomain.com/nl -> https://mydomain.com/nl (nl language)
+- https://en.mydomain.com -> https://en.mydomain.com/en (en language)
+- https://es.mydomain.com -> https://es.mydomain.com/es (es language)
+- https://fr.mydomain.com -> https://fr.mydomain.com/fr (fr language)
+- https://fr.mydomain.com/de -> https://fr.mydomain.com/de (de language)
+
+The same requests when using the `prefix_except_default` strategy, will be:
+- https://mydomain.com -> https://mydomain.com (en language)
+- https://mydomain.com/pl -> https://mydomain.com/pl (pl language)
+- https://mydomain.com/ua -> https://mydomain.com/ua (ua language)
+- https://mydomain.com/nl -> https://mydomain.com/nl (nl language)
+- https://en.mydomain.com -> https://en.mydomain.com (en language)
+- https://es.mydomain.com -> https://es.mydomain.com (es language)
+- https://fr.mydomain.com -> https://fr.mydomain.com (fr language)
+- https://fr.mydomain.com/de -> https://fr.mydomain.com/de (de language)
diff --git a/...t/docs/5.v9/2.guide/10.locale-fallback.md → ...t/docs/5.v9/2.guide/11.locale-fallback.md b/...t/docs/5.v9/2.guide/10.locale-fallback.md → ...t/docs/5.v9/2.guide/11.locale-fallback.md
diff --git a/.../2.guide/11.per-component-translations.md → .../2.guide/12.per-component-translations.md b/.../2.guide/11.per-component-translations.md → .../2.guide/12.per-component-translations.md
diff --git a/...t/docs/5.v9/2.guide/12.extend-messages.md → ...t/docs/5.v9/2.guide/13.extend-messages.md b/...t/docs/5.v9/2.guide/12.extend-messages.md → ...t/docs/5.v9/2.guide/13.extend-messages.md
diff --git a/...tent/docs/5.v9/2.guide/13.extend-pages.md → ...tent/docs/5.v9/2.guide/14.extend-pages.md b/...tent/docs/5.v9/2.guide/13.extend-pages.md → ...tent/docs/5.v9/2.guide/14.extend-pages.md
diff --git a/docs/content/docs/5.v9/2.guide/14.layers.md → docs/content/docs/5.v9/2.guide/15.layers.md b/docs/content/docs/5.v9/2.guide/14.layers.md → docs/content/docs/5.v9/2.guide/15.layers.md
diff --git a/...v9/2.guide/15.server-side-translations.md → ...v9/2.guide/16.server-side-translations.md b/...v9/2.guide/15.server-side-translations.md → ...v9/2.guide/16.server-side-translations.md
diff --git a/...nt/docs/5.v9/2.guide/16.install-module.md → ...nt/docs/5.v9/2.guide/17.install-module.md b/...nt/docs/5.v9/2.guide/16.install-module.md → ...nt/docs/5.v9/2.guide/17.install-module.md
diff --git a/...content/docs/5.v9/2.guide/17.migrating.md → ...content/docs/5.v9/2.guide/18.migrating.md b/...content/docs/5.v9/2.guide/17.migrating.md → ...content/docs/5.v9/2.guide/18.migrating.md
diff --git a/...5.v9/2.guide/18.breaking-changes-in-v9.md → ...5.v9/2.guide/19.breaking-changes-in-v9.md b/...5.v9/2.guide/18.breaking-changes-in-v9.md → ...5.v9/2.guide/19.breaking-changes-in-v9.md
diff --git a/docs/content/docs/5.v9/3.options/2.routing.md b/docs/content/docs/5.v9/3.options/2.routing.md
@@ -45,6 +45,8 @@ When using an object form, the properties can be:
 - `dir` - The dir property specifies the direction of the elements and content, value could be `'rtl'`, `'ltr'` or `'auto'`.
 - `domain` (required when using [`differentDomains`](/docs/options/domain#differentdomains)) - the domain name you'd like to use for that locale (including the port if used). This property can also be set using [`runtimeConfig`](/docs/options/runtime-config).
 - `domainDefault` (required when using [`differentDomains`](/docs/options/domain#differentdomains) while one or more of the domains having multiple locales) - set `domainDefault` to `true` for each locale that should act as a default locale for the particular domain.
+- `domains` (required when using [`multiDomainLocales`](/docs/options/domain#multiDomainLocales) while one or more of the domains having multiple of the same locales) - an array of [`domain`].
+- `defaultForDomains` (optional when using [`multiDomainLocales`](/docs/options/domain#multiDomainLocales)) - an array of [`domain`] for which the locale should be the default locale when using [`domains`].
 - `...` - any custom property set on the object will be exposed at runtime. This can be used, for example, to define the language name for the purpose of using it in a language selector on the page.
 
 You can access all the properties of the current locale through the `localeProperties` property. When using an array of codes, it will only include the `code` property.

diff --git a/docs/content/docs/5.v9/3.options/5.domain.md b/docs/content/docs/5.v9/3.options/5.domain.md
@@ -9,3 +9,10 @@ description: Browser locale management options.
 - default: `false`
 
 Set this to `true` when using different domains for each locale, with this enabled you MUST configure locales as an array of objects, each containing a `domain` key. Refer to the [Different domains](/docs/guide/different-domains) for more information.
+
+## `multiDomainLocales`
+
+- type: `boolean`
+- default: `false`
+
+Set this to `true` when using different domains with different locales. If enabled, you MUST configure locales as an array of objects, each containing a `domains` and `defaultForDomains` key. Refer to the [Multi Domain Locales](/docs/guide/multi-domain-locales) for more information.