Domini personalizzati

Intlayer supporta il routing delle locale basato su dominio, permettendoti di servire locale specifiche da hostname dedicati. Ad esempio, i visitatori cinesi possono essere indirizzati a intlayer.zh invece di intlayer.org/zh.

Come funziona

La mappa domains in routing associa ogni locale a un hostname. Intlayer utilizza questa mappa in due posti:

1. Generazione di URL (getLocalizedUrl): quando la locale di destinazione si trova su un dominio diverso dalla pagina corrente, viene restituito un URL assoluto (es. https://intlayer.zh/about). Quando entrambi i domini corrispondono, viene restituito un URL relativo (es. /fr/about).
2. Proxy del server (Next.js & Vite): le richieste in entrata vengono reindirizzate o riscritte in base al dominio su cui arrivano.

Domini esclusivi vs condivisi

La distinzione chiave è l'esclusività:

• Dominio esclusivo - solo una locale è mappata su quell'hostname (es. zh → intlayer.zh). Il dominio stesso identifica la locale, quindi nessun prefisso di locale viene aggiunto al percorso. https://intlayer.zh/about serve contenuti in cinese.
• Dominio condiviso - più locale sono mappate sullo stesso hostname (es. sia en che fr sono mappate su intlayer.org). Si applica il normale routing basato sui prefissi. intlayer.org/fr/about serve contenuti in francese.

Configurazione

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      Locales.CHINESE,
    ],
    defaultLocale: Locales.ENGLISH,
  },
  routing: {
    mode: "prefix-no-default",
    domains: {
      // Dominio condiviso - en e fr usano il routing dei prefissi su intlayer.org
      en: "intlayer.org",
      // Dominio esclusivo - zh ha il suo hostname dedicato, nessun prefisso /zh/ necessario
      zh: "intlayer.zh",
    },
  },
};

export default config;

Le locale non elencate in domains continuano a utilizzare il routing standard basato sui prefissi senza alcun override del dominio.

Generazione di URL

getLocalizedUrl produce automaticamente il tipo di URL corretto in base al contesto della chiamata.

Locale sullo stesso dominio (URL relativo)

// Pagina corrente: intlayer.org/about
getLocalizedUrl("/about", "fr", { currentDomain: "intlayer.org" });
// → "/fr/about"

getLocalizedUrl("/about", "en", { currentDomain: "intlayer.org" });
// → "/about"  (locale predefinita, nessun prefisso)

Locale su un dominio diverso (URL assoluto)

// Pagina corrente: intlayer.org/about
getLocalizedUrl("/about", "zh", { currentDomain: "intlayer.org" });
// → "https://intlayer.zh/about"  (dominio esclusivo, nessun prefisso /zh/)

Servire dal proprio dominio della locale

// Pagina corrente: intlayer.zh/about
getLocalizedUrl("/about", "zh", { currentDomain: "intlayer.zh" });
// → "/about"  (già sul dominio corretto - URL relativo)

getLocalizedUrl("/about", "fr", { currentDomain: "intlayer.zh" });
// → "https://intlayer.org/fr/about"  (link tra domini verso intlayer.org)

Rilevamento automatico del dominio corrente

currentDomain è facoltativo. Quando omesso, getLocalizedUrl lo risolve in questo ordine:

1. L'hostname di un URL di input assoluto (es. https://intlayer.org/about → intlayer.org).
2. window.location.hostname negli ambienti browser.
3. Se nessuno dei due è disponibile (SSR senza opzione esplicita), viene restituito un URL relativo per le locale dello stesso dominio e non viene prodotto alcun URL assoluto - questo è il fallback sicuro.

// Browser - window.location.hostname === 'intlayer.org'
getLocalizedUrl("/about", "zh");
// → "https://intlayer.zh/about"  (rilevato automaticamente dalla finestra)

// Da un URL assoluto - dominio rilevato automaticamente
getLocalizedUrl("https://intlayer.org/about", "zh");
// → "https://intlayer.zh/about"

getMultilingualUrls con domini

getMultilingualUrls chiama getLocalizedUrl per ogni locale, quindi produce un mix di URL relativi e assoluti a seconda del dominio del chiamante:

// currentDomain: 'intlayer.org'
getMultilingualUrls("/about", { currentDomain: "intlayer.org" });
// {
//   en: "/about",
//   fr: "/fr/about",
//   es: "/es/about",
//   zh: "https://intlayer.zh/about",
// }

Questi URL assoluti sono pronti per essere utilizzati nei tag <link rel="alternate" hreflang="..."> per la SEO.

Comportamento del Proxy

Next.js

Il middleware intlayerProxy gestisce automaticamente il routing di dominio. Aggiungilo al tuo middleware.ts:

export { intlayerProxy as default } from "next-intlayer/proxy";

export const config = {
  matcher: "/((?!api|static|assets|robots|sitemap|.*\\..*|_next).*)",
};

Redirect - la richiesta arriva sul dominio sbagliato per un determinato prefisso di locale:

GET intlayer.org/zh/about
→ 301 https://intlayer.zh/about

Rewrite - la richiesta arriva sul dominio esclusivo della locale senza un prefisso:

GET intlayer.zh/about
→ rewrite su /zh/about  (solo routing interno di Next.js, l'URL rimane pulito)

Vite

Il plugin Vite intlayerProxy applica la stessa logica durante lo sviluppo:

import { defineConfig } from "vite";
import { intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayerProxy()],
});

Nota: Nello sviluppo locale di solito ti trovi su localhost, quindi i reindirizzamenti tra domini punteranno ai domini live piuttosto che a un'altra porta locale. Utilizza una sostituzione nel file hosts (es. 127.0.0.1 intlayer.zh) o un reverse proxy se hai bisogno di testare il routing multi-dominio localmente.

Selettore della locale (Locale Switcher)

L'hook useLocale di next-intlayer gestisce automaticamente la navigazione consapevole del dominio. Quando un utente passa a una locale su un dominio diverso, l'hook esegue una navigazione di pagina completa (window.location.href) invece di un push del router lato client, perché il router di Next.js non può attraversare le origini.

"use client";

import { useLocale } from "next-intlayer";

export const LocaleSwitcher = () => {
  const { availableLocales, locale, setLocale } = useLocale();

  return (
    <ul>
      {availableLocales.map((localeEl) => (
        <li key={localeEl}>
          <button
            onClick={() => setLocale(localeEl)}
            aria-current={localeEl === locale ? "true" : undefined}
          >
            {l.toUpperCase()}
          </button>
        </li>
      ))}
    </ul>
  );
};

Nessuna configurazione extra è richiesta - useLocale rileva internamente window.location.hostname e decide tra router.replace (stesso dominio) e window.location.href (dominio diverso).

SEO: link alternativi hreflang

Il routing basato su dominio è comunemente usato insieme a hreflang per dire ai motori di ricerca quale URL indicizzare per ogni lingua. Usa getMultilingualUrls per generare il set completo di URL alternativi:

import { getMultilingualUrls } from "intlayer";
import type { Metadata } from "next";

export const generateMetadata = (): Metadata => {
  const alternates = getMultilingualUrls("/", {
    currentDomain: process.env.NEXT_PUBLIC_DOMAIN, // es. "intlayer.org"
  });

  return {
    alternates: {
      languages: alternates,
    },
  };
};

Questo produce:

<link rel="alternate" hreflang="en" href="https://intlayer.org/" />
<link rel="alternate" hreflang="fr" href="https://intlayer.org/fr/" />
<link rel="alternate" hreflang="es" href="https://intlayer.org/es/" />
<link rel="alternate" hreflang="zh" href="https://intlayer.zh/" />

Utility di base