Tên miền tùy chỉnh

Intlayer hỗ trợ điều hướng ngôn ngữ dựa trên tên miền, cho phép bạn phục vụ các ngôn ngữ cụ thể từ các tên miền riêng biệt. Ví dụ: khách truy cập từ Trung Quốc có thể được điều hướng đến intlayer.zh thay vì intlayer.org/zh.

Cách thức hoạt động

Bản đồ domains trong routing liên kết mỗi ngôn ngữ với một tên miền. Intlayer sử dụng bản đồ này ở hai nơi:

1. Tạo URL (getLocalizedUrl): khi ngôn ngữ mục tiêu nằm trên một tên miền khác với trang hiện tại, một URL tuyệt đối sẽ được trả về (ví dụ: https://intlayer.zh/about). Khi cả hai tên miền khớp nhau, một URL tương đối sẽ được trả về (ví dụ: /fr/about).
2. Proxy máy chủ (Next.js & Vite): Các yêu cầu đến sẽ được chuyển hướng hoặc ghi lại dựa trên tên miền mà chúng đến.

Tên miền độc quyền vs Tên miền chung

Sự khác biệt chính là tính độc quyền:

• Tên miền độc quyền - Chỉ một ngôn ngữ ánh xạ tới tên miền đó (ví dụ: zh → intlayer.zh). Bản thân tên miền đó xác định ngôn ngữ, vì vậy không có tiền tố ngôn ngữ nào được thêm vào đường dẫn. https://intlayer.zh/about phục vụ nội dung tiếng Trung.
• Tên miền chung - Nhiều ngôn ngữ ánh xạ tới cùng một tên miền (ví dụ: cả en và fr đều ánh xạ tới intlayer.org). Điều hướng dựa trên tiền tố thông thường sẽ được áp dụng. intlayer.org/fr/about phục vụ nội dung tiếng Pháp.

Cấu hình

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: {
      // Tên miền chung - en và fr sử dụng điều hướng tiền tố trên intlayer.org
      en: "intlayer.org",
      // Tên miền độc quyền - zh có tên miền riêng, không cần tiền tố /zh/
      zh: "intlayer.zh",
    },
  },
};

export default config;

Các ngôn ngữ không được liệt kê trong domains tiếp tục sử dụng điều hướng tiền tố tiêu chuẩn mà không có bất kỳ ghi đè tên miền nào.

Tạo URL

getLocalizedUrl tự động tạo loại URL chính xác dựa trên ngữ cảnh cuộc gọi.

Ngôn ngữ cùng tên miền (URL tương đối)

// Trang hiện tại: intlayer.org/about
getLocalizedUrl("/about", "fr", { currentDomain: "intlayer.org" });
// → "/fr/about"

getLocalizedUrl("/about", "en", { currentDomain: "intlayer.org" });
// → "/about" (ngôn ngữ mặc định, không tiền tố)

Ngôn ngữ khác tên miền (URL tuyệt đối)

// Trang hiện tại: intlayer.org/about
getLocalizedUrl("/about", "zh", { currentDomain: "intlayer.org" });
// → "https://intlayer.zh/about" (tên miền độc quyền, không có tiền tố /zh/)

Phục vụ từ chính tên miền của ngôn ngữ

// Trang hiện tại: intlayer.zh/about
getLocalizedUrl("/about", "zh", { currentDomain: "intlayer.zh" });
// → "/about" (đã ở đúng tên miền - URL tương đối)

getLocalizedUrl("/about", "fr", { currentDomain: "intlayer.zh" });
// → "https://intlayer.org/fr/about" (liên kết xuyên tên miền quay lại intlayer.org)

Tự động phát hiện tên miền hiện tại

currentDomain là tùy chọn. Khi được bỏ qua, getLocalizedUrl sẽ giải quyết nó theo thứ tự này:

1. Tên miền của một URL đầu vào tuyệt đối (ví dụ: https://intlayer.org/about → intlayer.org).
2. window.location.hostname trong môi trường trình duyệt.
3. Nếu không có cái nào khả dụng (SSR không có tùy chọn rõ ràng), một URL tương đối sẽ được trả về cho các ngôn ngữ cùng tên miền và không có URL tuyệt đối nào được tạo - đây là phương án dự phòng an toàn.

// Trình duyệt - window.location.hostname === 'intlayer.org'
getLocalizedUrl("/about", "zh");
// → "https://intlayer.zh/about" (tự động phát hiện từ window)

// Từ một URL tuyệt đối - tên miền được phát hiện tự động
getLocalizedUrl("https://intlayer.org/about", "zh");
// → "https://intlayer.zh/about"

getMultilingualUrls với tên miền

getMultilingualUrls gọi getLocalizedUrl cho mọi ngôn ngữ, vì vậy nó tạo ra sự kết hợp giữa URL tương đối và tuyệt đối tùy thuộc vào tên miền của người gọi:

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

Các URL tuyệt đối này đã sẵn sàng để sử dụng trong các thẻ <link rel="alternate" hreflang="..."> cho SEO.

Suy luận kiểu dữ liệu

routing.domains được serialize vào module augmentation được tạo, do đó getLocalizedUrl và getLocalizedPath thu hẹp kiểu trả về của chúng thành URL chính xác mà một locale được định tuyến theo domain sẽ phân giải thành — bao gồm cả việc loại bỏ prefix.

// routing: { mode: 'prefix-no-default', domains: { en: 'intlayer.org', zh: 'intlayer.zh' } }

getLocalizedUrl("/about", "zh");
//     ^? "https://intlayer.zh/about" | "/about"

getLocalizedPath("/about", "zh");
//     ^? "/about"   (không bao giờ là origin, và không có /zh/ prefix)

Kiểu URL là union của hai giá trị mà hàm có thể trả về: URL tuyệt đối trên domain của locale, và URL tương đối mà nó trả về khi trang đang được render đã nằm trên domain đó. getLocalizedPath không có sự mơ hồ như vậy - nó không bao giờ phát ra một origin - do đó nó vẫn là một literal duy nhất.

Các locale chia sẻ một domain sẽ giữ prefix bình thường của chúng trong kiểu như sau:

getLocalizedUrl("/about", "fr");
//     ^? "https://intlayer.org/fr/about" | "/fr/about"

Tái tạo các kiểu dữ liệu (npx intlayer build, hoặc bất kỳ lần chạy dev server nào) sau khi thay đổi routing.domains - việc thu hẹp đến từ __RoutingRegistry được tạo, chứ không phải từ chính tệp cấu hình.

Hành vi Proxy

Next.js

Phần mềm trung gian intlayerProxy tự động xử lý điều hướng tên miền. Thêm nó vào middleware.ts của bạn:

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

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

Chuyển hướng - yêu cầu đến sai tên miền cho một tiền tố ngôn ngữ nhất định:

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

Ghi lại (Rewrite) - yêu cầu đến tên miền độc quyền của ngôn ngữ mà không có tiền tố:

GET intlayer.zh/about
→ ghi lại thành /zh/about (chỉ điều hướng nội bộ Next.js, URL vẫn sạch sẽ)

Vite

Plugin Vite intlayerProxy áp dụng logic tương tự trong quá trình phát triển:

Kể từ Intlayer v9, intlayerProxy() được đóng gói trực tiếp vào plugin intlayer() và được bật mặc định thông qua tùy chọn routing.enableProxy (true theo mặc định). Đăng ký nó riêng biệt như hiển thị bên dưới hiện là tùy chọn — nó được giữ lại để tương thích ngược và cho các thiết lập cần kiểm soát thứ tự plugin. Đặt routing.enableProxy: false để từ chối. Xem ghi chú phát hành v9.

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

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

Lưu ý: trong quá trình phát triển cục bộ, bạn thường ở localhost, vì vậy các chuyển hướng xuyên tên miền sẽ trỏ đến các tên miền trực tiếp thay vì một cổng cục bộ khác. Sử dụng ghi đè tệp hosts (ví dụ: 127.0.0.1 intlayer.zh) hoặc một proxy ngược nếu bạn cần kiểm tra điều hướng đa tên miền cục bộ.

Trình chuyển đổi ngôn ngữ (Locale Switcher)

Hook useLocale từ next-intlayer tự động xử lý điều hướng nhận biết tên miền. Khi người dùng chuyển sang một ngôn ngữ trên một tên miền khác, hook thực hiện điều hướng toàn bộ trang (window.location.href) thay vì đẩy bộ định tuyến phía máy khách, vì bộ định tuyến Next.js không thể xuyên suốt các nguồn (origins).

"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}
          >
            {localeEl.toUpperCase()}
          </button>
        </li>
      ))}
    </ul>
  );
};

Không cần cấu hình thêm - useLocale tự động phát hiện window.location.hostname bên trong và quyết định giữa router.replace (cùng tên miền) và window.location.href (khác tên miền).

SEO: hreflang Liên kết thay thế

Điều hướng dựa trên tên miền thường được sử dụng cùng với hreflang để thông báo cho các công cụ tìm kiếm biết URL nào nên lập chỉ mục cho mỗi ngôn ngữ. Sử dụng getMultilingualUrls để tạo bộ URL thay thế đầy đủ:

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

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

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

Điều này tạo ra:

<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/" />

Các tiện ích cốt lõi