Domain routing for locales in NextJS - Step-by-Step Execution

Concept Flow - Domain routing for locales

User enters URL

↓

Next.js checks domain

↓

Match domain to locale config?

No→Use default locale

Yes↓

Set locale based on domain

↓

Render page with locale

↓

User sees localized content

Next.js checks the domain the user visits, matches it to a locale, then renders the page in that locale.

Execution Sample

NextJS

export const nextConfig = {
  i18n: {
    locales: ['en', 'fr'],
    defaultLocale: 'en',
    domains: [
      { domain: 'example.com', defaultLocale: 'en' },
      { domain: 'exemple.fr', defaultLocale: 'fr' }
    ]
  }
}

This config sets English for example.com and French for exemple.fr domains.

Execution Table

Step	User URL	Domain Matched	Locale Set	Page Rendered
1	https://example.com/home	example.com	en	Home page in English
2	https://exemple.fr/home	exemple.fr	fr	Home page in French
3	https://unknown.com/home	No match	en (default)	Home page in English
4	https://example.com/about	example.com	en	About page in English
5	https://exemple.fr/about	exemple.fr	fr	About page in French

💡 Execution stops after rendering the localized page based on domain or default locale.

Variable Tracker

Variable	Start	After 1	After 2	After 3	After 4	After 5
userURL	N/A	https://example.com/home	https://exemple.fr/home	https://unknown.com/home	https://example.com/about	https://exemple.fr/about
matchedDomain	N/A	example.com	exemple.fr	No match	example.com	exemple.fr
locale	en (default)	en	fr	en (default)	en	fr
pageRendered	N/A	Home page in English	Home page in French	Home page in English	About page in English	About page in French

Key Moments - 2 Insights

Why does the locale default to 'en' when the domain is unknown?

Because the execution_table row 3 shows 'No match' for domain, so Next.js uses the defaultLocale 'en' as configured.

How does Next.js know which locale to use for a domain?

Next.js matches the domain from the user URL to the domains array in the config, as shown in execution_table rows 1 and 2.

Visual Quiz - 3 Questions

Look at the execution_table, what locale is set when the user visits 'https://exemple.fr/home'?

A en

B defaultLocale

C fr

D No locale

💡 Hint

Check row 2 under 'Locale Set' in the execution_table.

At which step does the domain not match any configured domain?

A Step 1

B Step 3

C Step 5

D Step 2

💡 Hint

Look for 'No match' in the 'Domain Matched' column in execution_table.

If we add a new domain 'example.de' with defaultLocale 'de', what would happen when visiting 'https://example.de/home'?

A Locale would be 'de' and page rendered in German

B Locale would be 'en' as default

C No locale set, error occurs

D Locale would be 'fr'

💡 Hint

Refer to how domains map to locales in the execution_table and variable_tracker.

Concept Snapshot

Next.js domain routing for locales:
- Configure i18n.domains with domain and defaultLocale
- User visits URL
- Next.js matches domain to locale
- If no match, uses defaultLocale
- Page renders in matched locale
- Enables localized content by domain

Full Transcript

Domain routing for locales in Next.js means the app looks at the domain name the user visits. It checks if the domain matches any configured domain in the i18n.domains array. If it matches, Next.js sets the locale to the domain's defaultLocale. If no domain matches, it uses the defaultLocale set globally. Then the page renders with content in that locale. For example, example.com shows English content, while exemple.fr shows French. This lets websites serve different languages on different domains automatically.

Practice

1. What is the main purpose of domain routing for locales in Next.js?

easy

A. To enable client-side routing only

B. To improve server performance by caching

C. To create multiple apps in one project

D. To serve different languages on different domains

Solution

1. Step 1: Understand domain routing concept

   Domain routing allows serving different languages or locales on separate domains or subdomains.

2. Step 2: Identify the main use case in Next.js

   Next.js uses domain routing to link domains to specific locales for internationalization.

3. Final Answer:

   To serve different languages on different domains -> Option D

4. Quick Check:

   Domain routing = serve languages on domains [OK]

Hint: Domain routing connects domains to languages [OK]

Common Mistakes:

• Confusing domain routing with caching
• Thinking it only affects client-side routing
• Assuming it creates multiple apps

2. Which Next.js config property is used to define domain routing for locales?

easy

A. routing.locales

B. i18n.domains

C. locales.domains

D. next.config.domains

Solution

1. Step 1: Recall Next.js i18n config structure

   The internationalization config uses the i18n key in next.config.js.

2. Step 2: Identify the property for domain routing

   The correct property to define domain-locale mapping is i18n.domains.

3. Final Answer:

   i18n.domains -> Option B

4. Quick Check:

   Domain routing config = i18n.domains [OK]

Hint: Look inside i18n config for domains key [OK]

Common Mistakes:

• Using next.config.domains instead of i18n.domains
• Confusing with routing.locales
• Trying to set domains outside i18n

3. Given this Next.js i18n config snippet, what locale will be served for requests to https://example.fr?

i18n: {
  locales: ['en', 'fr'],
  defaultLocale: 'en',
  domains: [
    { domain: 'example.com', defaultLocale: 'en' },
    { domain: 'example.fr', defaultLocale: 'fr' }
  ]
}

medium

A. fr

B. en

C. defaultLocale from browser

D. No locale, error occurs

Solution

1. Step 1: Check domain-locale mapping in config

   The domain example.fr is mapped to fr locale explicitly.

2. Step 2: Determine locale served for example.fr

   Requests to example.fr will serve the French locale fr.

3. Final Answer:

   fr -> Option A

4. Quick Check:

   example.fr domain = fr locale [OK]

Hint: Match domain to locale in i18n.domains array [OK]

Common Mistakes:

• Assuming defaultLocale 'en' applies to all domains
• Thinking browser locale overrides domain
• Believing error occurs without explicit locale

4. You wrote this middleware to detect locale by domain but it always serves the default locale. What is the likely mistake?

export function middleware(request) {
  const hostname = request.headers.get('host')
  if (hostname === 'example.fr') {
    return NextResponse.rewrite(new URL('/fr', request.url))
  }
  return NextResponse.next()
}

medium

A. Rewriting to '/fr' instead of setting locale cookie

B. Not returning a response for all domains

C. Using 'host' header instead of 'x-forwarded-host'

D. Middleware missing 'export default'

Solution

1. Step 1: Understand middleware role in locale detection

   Middleware should set locale or rewrite URL to include locale prefix properly.

2. Step 2: Identify issue with rewriting only

   Rewriting to '/fr' alone may not set locale context; locale cookie or header is needed for Next.js to recognize locale.

3. Final Answer:

   Rewriting to '/fr' instead of setting locale cookie -> Option A

4. Quick Check:

   Middleware must set locale, not just rewrite URL [OK]

Hint: Middleware must set locale, not just rewrite URL [OK]

Common Mistakes:

• Assuming host header is wrong
• Forgetting to handle all domains
• Missing export default in middleware

5. How would you configure Next.js to serve English on 'example.com' and French on 'example.fr' using domain routing, ensuring the default locale is English and URLs do not show locale prefixes?

hard

A. Set i18n.locales to ['en', 'fr'], defaultLocale to 'en', and i18n.domains with domains for example.com (fr) and example.fr (en), and use localeDetection: true

B. Set i18n.locales to ['en', 'fr'], defaultLocale to 'fr', and i18n.domains with domains for example.com (fr) and example.fr (en), and use localeDetection: true

C. Set i18n.locales to ['en', 'fr'], defaultLocale to 'en', and i18n.domains with domains for example.com (en) and example.fr (fr), and use localeDetection: false

D. Set i18n.locales to ['en', 'fr'], defaultLocale to 'en', and no domains, rely on middleware only

Solution

1. Step 1: Define locales and defaultLocale correctly

   Locales should be ['en', 'fr'] with defaultLocale 'en' to serve English by default.

2. Step 2: Configure i18n.domains for domain-locale mapping

   Map 'example.com' to 'en' and 'example.fr' to 'fr' in i18n.domains array.

3. Step 3: Disable localeDetection to avoid prefix in URLs

   Setting localeDetection: false prevents Next.js from adding locale prefixes in URLs, serving clean domain-based locales.

4. Final Answer:

   Set i18n.locales to ['en', 'fr'], defaultLocale to 'en', and i18n.domains with domains for example.com (en) and example.fr (fr), and use localeDetection: false -> Option C

5. Quick Check:

   Domain routing + defaultLocale + no prefix = Set i18n.locales to ['en', 'fr'], defaultLocale to 'en', and i18n.domains with domains for example.com (en) and example.fr (fr), and use localeDetection: false [OK]

Hint: Use i18n.domains and disable localeDetection for clean URLs [OK]

Common Mistakes:

• Swapping locales for domains
• Forgetting to disable localeDetection
• Relying only on middleware without domains