如何在使用 Pages Router 的 Next.js 應用程式中實作國際化
透過國際化 (i18n),讓你的 React 應用程式更具可及性,並開拓新市場。
隨著世界日益全球化,網頁開發者建構能夠滿足不同國家與文化使用者的應用程式變得越來越重要。實現這一目標的關鍵方法之一是國際化(i18n),它讓您能將應用程式調整為不同語言、貨幣與日期格式。
在本教學中,我們將探討如何為您的 React Next.js 應用加入國際化,並實現伺服器端渲染。 TL;DR: 在此查看完整範例。
本指南適用於使用 Pages Router 的 Next.js 應用程式。
如果您使用 App Router,請改為參閱這份指南。
步驟 1: 安裝 i18n 函式庫
要在你的 Next.js 應用程式中實作國際化(i18n),我們會先選擇一個 i18n 函式庫。市面上有幾個流行的函式庫可供選擇,包括 next-intl. 不過,在本範例中,我們將使用 TacoTranslate.
TacoTranslate 使用最先進的 AI 自動將你的字串翻譯成任何語言,並讓你免於繁瑣的 JSON 檔案管理。
讓我們在終端機中使用 npm 安裝它:
npm install tacotranslate
步驟 2: 建立一個免費的 TacoTranslate 帳戶
現在你已經安裝好該模組,接下來是建立你的 TacoTranslate 帳戶、翻譯專案以及相關的 API 金鑰。在此建立一個帳戶。 它是免費的,且 不需要你提供信用卡資訊。
在 TacoTranslate 應用程式的 UI 中,建立一個專案,然後前往其 API keys 分頁。建立一個 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。在此閱讀更多關於來源的資訊。
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
。
將 client 建立在獨立的檔案中,日後更容易再次使用。現在,使用自訂的 /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 屬性。請注意, revalidate
在 getTacoTranslateStaticProps
上預設為 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!"/>;
}
你現在應該可以在所有的 React 組件中使用 Translate
元件來翻譯字串。
import {Translate} from 'tacotranslate/react';
function Component() {
return <Translate string="Hello, world!"/>
}
步驟 5: 部署並測試!
完成了!當您將任何字串加入到 Translate
元件時,您的 React 應用程式現在會自動被翻譯。請注意,只有在 API 金鑰具有 read/write
權限的環境,才能建立新的要翻譯的字串。我們建議設置一個封閉且安全的暫存(staging)環境,在那裡使用該類 API 金鑰測試您的生產應用程式,並在上線前新增字串。這樣可以防止任何人任何人竊取您的秘密 API 金鑰,並可能避免因新增不相關的字串而使翻譯專案膨脹。
請務必到我們的 GitHub 頁面 查看完整範例。那裡你也會找到一個使用 App Router 的範例!如果你遇到任何問題,歡迎透過 聯絡我們,我們會很樂意協助你。
TacoTranslate 讓你能夠自動且快速地在超過 75 種語言之間本地化你的 React 應用程式。 立即開始使用!