如何在使用 App Router 的 Next.js 應用程式中實現國際化
使您的 React 應用程式更具可及性，並藉由國際化 (i18n) 拓展新市場。
隨著世界日益全球化，對網頁開發者來說，建立能夠滿足來自不同國家和文化用戶需求的應用程式變得越來越重要。實現這一目標的關鍵方式之一是透過國際化（i18n），使您的應用程式能夠適應不同的語言、貨幣和日期格式。
在本文中，我們將探討如何為您的 React Next.js 應用程式添加國際化功能，並實現伺服器端渲染。 TL;DR: 在此查看完整範例。
本指南適用於使用 App Router 的 Next.js 應用程式。
如果您使用的是 Pages Router，請參考此指南。
步驟 1： 安裝 i18n 函式庫
要在您的 Next.js 應用程式中實現國際化，我們將首先選擇一個 i18n 函式庫。有幾個流行的函式庫，包括 next-intl。不過，在本例中，我們將使用 TacoTranslate。
TacoTranslate 利用尖端的 AI 自動將您的字串翻譯成任何語言，並且免除您繁瑣的 JSON 檔案管理工作。
讓我們在終端機中使用 npm 安裝它：
npm install tacotranslate步驟 2： 創建一個免費的 TacoTranslate 帳戶
現在您已安裝好模組，該是時候建立您的 TacoTranslate 帳戶、一個翻譯專案，以及相關的 API 金鑰了。在此建立帳戶。 這是免費的，並且 不需要您提供信用卡資訊。
在 TacoTranslate 應用程式的 UI 中，建立一個專案，並導航到其 API 金鑰標籤。建立一個 read 金鑰和一個 read/write 金鑰。我們將把它們儲存為環境變數。 read 金鑰是我們所稱的 public，而 read/write 金鑰是 secret]。例如，您可以將它們加入專案根目錄的 .env 檔案中。
TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010請務必不要將秘密 read/write API 金鑰洩漏到客戶端的生產環境中。
我們還會新增另外兩個環境變數：TACOTRANSLATE_DEFAULT_LOCALE 及 TACOTRANSLATE_ORIGIN。
TACOTRANSLATE_DEFAULT_LOCALE：預設的回退語系代碼。在此範例中，我們將其設為en，代表英文。TACOTRANSLATE_ORIGIN：您的字串將被存放的「資料夾」，例如您的網站的 URL。在此閱讀更多關於 origins 的資訊。
TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com步驟 3： 設定 TacoTranslate
要將 TacoTranslate 整合到您的應用程式中，您需要使用之前的 API 金鑰來建立一個客戶端。例如，建立一個名為 /tacotranslate-client.js 的檔案。
const {default: createTacoTranslateClient} = require('tacotranslate');
const tacoTranslate = createTacoTranslateClient({
apiKey:
process.env.TACOTRANSLATE_SECRET_API_KEY ??
process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
process.env.TACOTRANSLATE_API_KEY,
projectLocale:
process.env.TACOTRANSLATE_IS_PRODUCTION === 'true'
? process.env.TACOTRANSLATE_PROJECT_LOCALE
: undefined,
});
module.exports = tacoTranslate;我們將會自動定義 TACOTRANSLATE_API_KEY 和 TACOTRANSLATE_PROJECT_LOCALE。
將客戶端創建放在單獨的檔案中，方便日後再次使用。getLocales 只是一個帶有內建錯誤處理的工具函式。現在，建立一個名為 /app/[locale]/tacotranslate.tsx 的檔案，我們將在其中實作 TacoTranslate 提供者。
'use client';
import React, {type ReactNode} from 'react';
import {
type TranslationContextProperties,
TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';
export default function TacoTranslate({
locale,
origin,
localizations,
children,
}: TranslationContextProperties & {
readonly children: ReactNode;
}) {
return (
<ImportedTacoTranslate
client={tacoTranslateClient}
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</ImportedTacoTranslate>
);
}注意 'use client'; 表示這是一個客戶端組件。
現在上下文提供者已經準備好，請建立一個名為 /app/[locale]/layout.tsx 的檔案，這是我們應用程式中的根佈局。請注意，此路徑中的資料夾使用了 Dynamic Routes，其中 [locale] 是動態參數。
import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';
export async function generateStaticParams() {
const locales = await tacoTranslateClient.getLocales();
return locales.map((locale) => ({locale}));
}
type RootLayoutParameters = {
readonly params: Promise<{locale: Locale}>;
readonly children: ReactNode;
};
export default async function RootLayout({params, children}: RootLayoutParameters) {
const {locale} = await params;
const origin = process.env.TACOTRANSLATE_ORIGIN;
const localizations = await tacoTranslateClient.getLocalizations({
locale,
origins: [origin /* , other origins to fetch */],
});
return (
<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
<body>
<TacoTranslate
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</TacoTranslate>
</body>
</html>
);
}這裡首先要注意的是，我們使用了 Dynamic Route 參數 [locale] 來獲取該語言的翻譯。此外，generateStaticParams 確保您專案中啟用的所有語言代碼都已預先渲染。
現在，讓我們建立第一個頁面！創建一個名為 /app/[locale]/page.tsx 的檔案。
import React from 'react';
import {Translate} from 'tacotranslate/react';
export const revalidate = 60;
export default async function Page() {
return (
<Translate string="Hello, world!" />
);
}請注意 revalidate 變數，該變數告訴 Next.js 在 60 秒後重新建構頁面，並保持您的翻譯內容是最新的。
步驟 4： 實作伺服器端渲染
TacoTranslate 支援伺服器端渲染。這大大提升了用戶體驗，能立即顯示已翻譯的內容，而非先出現未翻譯內容的閃現。此外，我們可以省略客戶端的網路請求，因為我們已經擁有使用者正在瀏覽頁面所需的翻譯內容。
要設定伺服器端渲染，請建立或修改 /next.config.js：
const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');
module.exports = async () => {
const config = await withTacoTranslate(
{},
{
client: tacoTranslateClient,
isProduction:
process.env.TACOTRANSLATE_ENV === 'production' ||
process.env.VERCEL_ENV === 'production' ||
(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
process.env.NODE_ENV === 'production'),
}
);
// NOTE: Remove i18n from config when using the app router
return {...config, i18n: undefined};
};修改 isProduction 檢查以適合您的設置。如果 true，TacoTranslate 將顯示公有 API 金鑰。如果我們在本地、測試或暫存環境 （isProduction is false） 中，我們將使用密鑰 read/write API 金鑰來確保發送新字串進行翻譯。
為了確保路由和重定向能如預期運作，我們需要建立一個名為 /middleware.ts 的檔案。透過使用 Middleware，我們可以將用戶導向以其偏好語言呈現的頁面。
import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';
export const config = {
matcher: ['/((?!api|_next|favicon.ico).*)'],
};
export async function middleware(request: NextRequest) {
return tacoTranslateMiddleware(tacoTranslate, request);
}請務必依照 Next.js 中介軟體文件 設定 matcher。
在客戶端，您可以更改 locale cookie 來改變使用者偏好的語言。請參考 完整的範例代碼，了解如何實現！
步驟 5： 部署並測試！
我們完成了！當你將任何字串加入到 Translate 元件時，你的 React 應用程式現在將自動進行翻譯。請注意，只有擁有 read/write 權限的 API 金鑰環境才能建立新的字串進行翻譯。我們建議你設置一個封閉且安全的測試環境，在那裡使用此類 API 金鑰測試你的生產應用程式，並在正式上線前新增字串。這將防止任何人竊取你的秘密 API 金鑰，並避免因新增無關字串而導致你的翻譯專案膨脹。
Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the Pages Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.
TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!