next-intl-docs

next-intl 4

此技能涵蓋 next-intl 4.x，內容基於 https://next-intl.dev/docs/getting-started（文件版本 4.14.9）。它記錄了與常見習慣不同的部分：令人意外的預設值、常見陷阱、舊版 API，以及文件推薦的模式。參考檔案中的每個說法末尾都標明了出處頁面。

如何瀏覽

1. 先閱讀底下的快速入門與快速規則，它們涵蓋了最常見的錯誤。
2. 根據任務，從底下的表格中開啟對應的參考檔案。
3. 當程式碼使用 setRequestLocale、requestLocale 或 middleware.ts 時，請先閱讀「舊模式」表格。

快速入門 (App Router)

App Router 是推薦路徑。Pages Router 仍受支援，請參閱 references/setup.md。 https://next-intl.dev/docs/getting-started/pages-router

// next.config.ts
import {NextConfig} from 'next';
import createNextIntlPlugin from 'next-intl/plugin';

const nextConfig: NextConfig = {};
const withNextIntl = createNextIntlPlugin();
export default withNextIntl(nextConfig);

https://next-intl.dev/docs/getting-started/app-router

不使用基於語系的 URL 時，src/i18n/request.ts 會從使用者偏好或 Cookie（最簡單的方式）來解析語系：

// src/i18n/request.ts
import {cookies} from 'next/headers';
import {getRequestConfig} from 'next-intl/server';

export default getRequestConfig(async () => {
  const store = await cookies();
  const locale = store.get('locale')?.value || 'en';
  return {
    locale,
    messages: (await import(`../../messages/${locale}.json`)).default
  };
});

https://next-intl.dev/docs/getting-started/app-router

// src/app/layout.tsx
import {NextIntlClientProvider} from 'next-intl';
import {getLocale} from 'next-intl/server';

export default async function RootLayout({children}) {
  const locale = await getLocale();
  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider>{children}</NextIntlClientProvider>
      </body>
    </html>
  );
}

https://next-intl.dev/docs/getting-started/app-router , https://next-intl.dev/docs/usage/configuration

import {useTranslations} from 'next-intl';
import {getTranslations} from 'next-intl/server';

export function HomePage() {
  const t = useTranslations('HomePage'); // 非 async 元件
  return <h1>{t('title')}</h1>;
}

export async function Profile() {
  const t = await getTranslations('ProfilePage'); // async 元件
  return <h1>{t('title')}</h1>;
}

https://next-intl.dev/docs/getting-started/app-router

如需 /en/about 這種風格的 URL，請新增 src/i18n/routing.ts、src/proxy.ts、src/i18n/navigation.ts 以及頂層的 [locale] 區段：請參閱 references/routing.md。 https://next-intl.dev/docs/routing/setup

快速規則

設定

• 外掛會尋找 src/ 或專案根目錄下的 i18n/request.ts（支援 .ts、.tsx、.js、.jsx 副檔名）。若檔案在其他位置，請傳入路徑：createNextIntlPlugin('./somewhere/else/request.ts')。 https://next-intl.dev/docs/getting-started/app-router
• 文件範例中寫死的 const locale = 'en' 應替換為真正的解析邏輯（Cookie、使用者設定或 next/root-params）。 https://next-intl.dev/docs/getting-started/app-router
• getRequestConfig 在每次請求的 Server Components 渲染階段執行一次，因此 cookies() 和 headers() 可在其中運作。 https://next-intl.dev/docs/usage/configuration
• 請在請求設定中設定 timeZone。預設為伺服器執行環境的時區。 https://next-intl.dev/docs/usage/configuration

路由

• 在 Next.js 16 中，請將檔案命名為 src/proxy.ts。匯入時仍使用 next-intl/middleware 的 createMiddleware。 https://next-intl.dev/docs/routing/setup
• 使用 await rootParams.locale() 從 next/root-params 讀取語系，並以 hasLocale(routing.locales, value) 進行驗證，若不合法則呼叫 notFound()。Next.js 16.3 之前的版本需要啟用 experimental.rootParams。 https://next-intl.dev/docs/routing/setup
• 請從您自訂的 i18n/navigation.ts 中匯入 Link、redirect、usePathname、useRouter 和 getPathname，而非從 next/link 或 next/navigation。 https://next-intl.dev/docs/routing/navigation
• 使用該模組的 router.replace(pathname, {locale}) 來切換語系。<Link locale> 不會被 prefetch，以避免覆蓋語系 Cookie。 https://next-intl.dev/docs/routing/navigation
• redirect 始終需要語系參數：redirect({href: '/login', locale})。請加上 return redirect(...) 讓 TypeScript 能正確進行型別縮減。 https://next-intl.dev/docs/routing/navigation
• 預設的比對器會跳過帶有句點的路徑。請為像 /users/jane.doe 這樣的路由明確加入比對條目。 https://next-intl.dev/docs/routing/middleware

用戶端元件

• 若 NextIntlClientProvider 未傳遞 messages prop，所有訊息都會被送到用戶端。請傳遞 messages={pick(messages, 'Namespace')} 或 messages={null} 來限制傳送的訊息量。 https://next-intl.dev/docs/environments/server-client-components
• 建議在 Server Component 中進行翻譯，然後將翻譯後的文字作為 prop 或 children 傳遞給 Client Component。 https://next-intl.dev/docs/environments/server-client-components
• onError 和 getMessageFallback 無法從 Server Component 傳遞。請在您自訂的 'use client' Provider 中設定它們，並將其巢狀在 Server Provider 之內，這樣子 Provider 會繼承語系和訊息，因此無需再手動傳遞這些東西。 https://next-intl.dev/docs/usage/configuration

訊息

• 鍵名和命名空間不能包含 .，這代表無法使用巢狀鍵名。請使用巢狀的 JSON 結構。 https://next-intl.dev/docs/usage/translations
• ICU 的引數名稱和 select 的值允許字母、數字和底線 _，不允許連字號：請將 en-GB 映射為 en_GB。select 需要一個 other 分支。 https://next-intl.dev/docs/usage/translations
• 自閉合標籤需要在訊息中使用閉合標籤：如 <br></br>。 https://next-intl.dev/docs/usage/translations
• 在 Server Actions、後設資料和 Route Handlers 中，請使用 getTranslations({locale, namespace})，因為在這些環境中語系可能無法被自動推斷。 https://next-intl.dev/docs/environments/actions-metadata-route-handlers

測試

• 與 createNavigation 搭配的 Vitest：server.deps.inline: ['next-intl']。Jest：transformIgnorePatterns: ['node_modules/(?!next-intl)/']。next-intl 是純 ESM 套件。 https://next-intl.dev/docs/environments/testing

舊模式

舊模式	新模式
src/middleware.ts	在 Next.js 16 中改用 src/proxy.ts，createMiddleware 的程式碼相同
在每個 layout 和 page 頂層使用 setRequestLocale(locale)	在 i18n/request.ts 中使用 next/root-params，無需此設定即可進行靜態渲染
getRequestConfig(async ({requestLocale}) => ...)	getRequestConfig(async ({locale}) => ...) 並加上 rootParams.locale() 作為後備方案
扁平化的訊息鍵名，如 "HomePage.title"	巢狀物件，如 {"HomePage": {"title": ...}}
搭配 dangerouslySetInnerHTML 使用的 t.raw HTML	使用 t.rich (React) 或 t.markup (字串)，t.raw 僅用於跳過解析（已淨化）的場合

詳細資訊請見：references/routing.md 和 references/messages.md。

參考檔案

檔案	用途
references/setup.md	外掛、請求設定、Provider 預設值、無路由的語系、訊息儲存、Pages Router
references/routing.md	defineRouting、[locale] 區段、proxy.ts、比對器、next/root-params、靜態渲染、localePrefix、網域、Cookie、替代連結、本地化路徑名、靜態匯出、疑難排解
references/navigation.md	createNavigation、Link、useRouter、usePathname、redirect、getPathname、語系切換器、型別安全的 href
references/messages.md	useTranslations、命名空間、ICU 複數與選擇、富文本、t.markup、t.raw、t.has、陣列、遺失訊息、onError、時區、now
references/formatting.md	useFormatter：日期、相對時間、範圍、數字、清單、顯示名稱、ICU 骨架、全域格式
references/server-and-client.md	Server 與 Client 元件、選擇性傳遞訊息、後設資料、Server Actions、Zod、Route Handlers、網站地圖、OG 圖片、404 與錯誤頁面
references/extraction.md	實驗性的 useExtracted 和 getExtracted、外掛 experimental 選項、PO 檔案、預先編譯、自訂轉碼器、Monorepo
references/typescript-and-tooling.md	AppConfig 型別擴充、型別安全引數、Jest 與 Vitest 測試、Storybook、use-intl 核心、執行時期需求、程式碼檢查、翻譯管理、代理約定

已爬取的頁面：SOURCES.md。