如何在使用 Pages Router 的 Next.js 應用程式中實現國際化
使您的 React 應用程式更易於使用,並透過國際化 (i18n) 開拓新市場。
隨著世界日益全球化,網頁開發者建立能夠滿足不同國家和文化用戶需求的應用程式變得越來越重要。實現這一目標的關鍵方法之一是通過國際化(i18n),讓您的應用程式能夠適應不同的語言、貨幣和日期格式。
在本教程中,我們將探討如何為您的 React Next.js 應用程式添加支持伺服器端渲染的國際化功能。 TL;DR: 請在此查看完整示例。
本指南適用於使用 Pages Router 的 Next.js 應用程式。
如果您使用的是 App Router,請參考此指南。
步驟 1: 安裝 i18n 函式庫
要在您的 Next.js 應用程式中實現國際化,我們首先會選擇一個 i18n 函式庫。有幾個流行的函式庫,包括 next-intl。不過,在這個範例中,我們將使用 TacoTranslate。
TacoTranslate 利用最先進的 AI 自動將您的字串翻譯成任何語言,並讓您擺脫繁瑣的 JSON 檔案管理。
讓我們使用 npm 在終端機中安裝它:
npm install tacotranslate
步驟 2: 創建一個免費的 TacoTranslate 帳戶
既然你已經安裝了該模組,現在是時候創建你的 TacoTranslate 帳戶、翻譯專案及相關的 API 金鑰了。在這裡創建帳戶。 這是免費的,且不需要你提供信用卡資訊。
在 TacoTranslate 應用程式的使用者介面中,建立一個專案,並導航至其 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_DEFAULT_LOCALE ?? '',
});
module.exports = tacoTranslate;
我們將很快自動定義 TACOTRANSLATE_API_KEY
。
將客戶端建立在一個獨立的檔案中,之後使用起來會更方便。現在,使用自訂的 /pages/_app.tsx
,我們將加入 TacoTranslate
提供者。
import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';
type PageProperties = {
origin: Origin;
locale: Locale;
locales: Locale[];
localizations: Localizations;
};
export default function App({Component, pageProps}: AppProps<PageProperties>) {
const {origin, locale, locales, localizations} = pageProps;
return (
<TacoTranslate
client={tacoTranslate}
origin={origin}
locale={locale}
localizations={localizations}
>
<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
<Component {...pageProps} />
</TacoTranslate>
);
}
如果您已經有自訂的 pageProps
和 _app.tsx
,請使用上述的屬性和程式碼來擴充定義。
步驟 4: 實作伺服器端渲染
TacoTranslate 允許您的翻譯進行伺服器端渲染。這大大提升了用戶體驗,因為能立即顯示已翻譯的內容,而不是先出現一閃而逝的未翻譯內容。此外,我們還能跳過客戶端的網路請求,因為我們已經擁有所需的所有翻譯。
我們將從建立或修改 /next.config.js
開始。
const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');
module.exports = async () => {
const config = {};
return withTacoTranslate(config, {
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'),
});
};
修改 isProduction
檢查以適合您的設置。如果 true
,TacoTranslate 將顯示公有 API 金鑰。如果我們在本地、測試或暫存環境 (isProduction
is false
) 中,我們將使用密鑰 read/write
API 金鑰來確保發送新字串進行翻譯。
直到現在,我們只為 Next.js 應用程式設定了支援的語言列表。接下來,我們將為您的所有頁面抓取翻譯。為此,您將根據需求使用 getTacoTranslateStaticProps
或 getTacoTranslateServerSideProps
。
這些函數接受三個參數:一個 Next.js Static Props Context 物件、一個 TacoTranslate 的設定,以及可選的 Next.js 屬性。請注意 getTacoTranslateStaticProps
中的 revalidate
預設為 60,以確保您的翻譯能保持最新。
若要在頁面中使用其中任一函數,假設您有一個頁面檔案如 /pages/hello-world.tsx
。
import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';
export async function getStaticProps(context) {
return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}
export default function Page() {
return <Translate string="Hello, world!"/>;
}
您現在應該能夠使用 Translate
元件來翻譯您所有 React 組件中的字串。
import {Translate} from 'tacotranslate/react';
function Component() {
return <Translate string="Hello, world!"/>
}
步驟 5: 部署並測試!
我們完成了!當你將任何字串加入 Translate
元件時,你的 React 應用將自動被翻譯。請注意,只有擁有 read/write
權限的 API 金鑰環境才能建立新的翻譯字串。我們建議你設置一個封閉且安全的測試環境,在那裡可以使用這類 API 金鑰測試你的生產應用,並在上線前新增字串。這樣可以防止任何人盜用你的秘密 API 金鑰,並避免因添加不相關的新字串而使翻譯專案不必要地膨脹。
請務必在我們的 GitHub 頁面查看完整範例。在那裡,您還會找到使用 App Router 的範例!如果您遇到任何問題,隨時聯絡我們,我們將非常樂意提供協助。
TacoTranslate 讓您能夠快速將 React 應用程式自動本地化到超過 75 種語言及其反向翻譯。立即開始使用!