כיצד ליישם בינלאומיות (i18n) באפליקציית Next.js שמשתמשת ב-App Router

ככל שהעולם נעשה גלובלי יותר, חשוב יותר ויותר שמפתחי ווב יבנו יישומים שיכולים להתאים למשתמשים ממדינות ותרבויות שונות. אחת הדרכים המרכזיות להשגת זאת היא באמצעות בינאום (i18n), שמאפשר להתאים את היישום לשפות שונות, מטבעות ופורמטים של תאריכים.

במאמר זה נסקור כיצד להוסיף בינאום ליישום ה-React Next.js שלך, כולל רינדור בצד השרת. TL;DR: צפה בדוגמה המלאה כאן.

מדריך זה מיועד ליישומי Next.js המשתמשים בApp Router.
אם אתם משתמשים בPages Router, ראו מדריך זה במקום.

שלב 1: התקן ספריית i18n

כדי ליישם בינלאומיות (i18n) באפליקציית Next.js שלך, נבחר תחילה ספריית i18n. ישנן מספר ספריות פופולריות, כולל next-intl. בדוגמה זו, עם זאת, נשתמש ב־TacoTranslate.

TacoTranslate מתרגם אוטומטית את המחרוזות שלך לכל שפה באמצעות בינה מלאכותית מתקדמת, ומשחרר אותך מהניהול המייגע של קבצי 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

וודא שלעולם לא תדלוף את מפתח ה-API הסודי read/write לסביבת הפרודקשן בצד הלקוח.

נוסיף גם שני משתני סביבה נוספים: TACOTRANSLATE_DEFAULT_LOCALE ו-TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: קוד המקומיות שישמש כברירת מחדל כגיבוי. בדוגמה זו נגדיר אותו כ-en עבור אנגלית.
• TACOTRANSLATE_ORIGIN: התיקייה שבה יאוחסנו המחרוזות שלך, כגון כתובת האתר שלך. למידע נוסף על המקורות כאן.

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) — נשתמש במפתח ה‑API הסודי read/write כדי לוודא שמחרוזות חדשות נשלחות לתרגום.

על מנת להבטיח שהניתוב וההפניות יעבדו כמצופה, נצטרך ליצור קובץ בשם /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);
}

ודא להגדיר את matcher בהתאם ל-תיעוד ה‑Middleware של Next.js.

בצד הלקוח ניתן לשנות את ה-cookie של locale כדי לשנות את השפה המועדפת של המשתמש. עיין ב-קוד הדוגמה המלא לקבלת רעיונות כיצד לעשות זאת!

שלב 5: פרוס ובדוק!

סיימנו! יישום ה-React שלך יתורגם כעת אוטומטית כאשר תוסיף כל מחרוזת לרכיב Translate. שים לב שרק סביבות שיש להן הרשאות 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!