כיצד ליישם בין-לאומיות (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: התיקייה שבה יאוחסנו המחרוזות שלך, כגון כתובת האתר שלך. קרא עוד על 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'; המציין שמדובר ברכיב בצד הלקוח.

כעת, כשהספק ההקשר (context provider) מוכן לשימוש, צרו קובץ בשם /app/[locale]/layout.tsx, תבנית השורש (root layout) באפליקציה שלנו. שימו לב שנתיב זה כולל תיקייה המשתמשת ב־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 מוודא שכל קודי ה-locale שהפעלת לפרויקט שלך ייווצרו מראש.

עכשיו בואו נבנה את הדף הראשון שלנו! צרו קובץ בשם /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.

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

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

סיימנו! אפליקציית React שלך תתורגם מעכשיו אוטומטית כשאתה מוסיף מחרוזות כלשהן לרכיב Translate. שים לב שרק סביבות שיש להן הרשאות read/write על מפתח ה־API יוכלו ליצור מחרוזות חדשות לתרגום. אנו ממליצים להחזיק סביבת בדיקות (staging) סגורה ומאובטחת שבה תוכל לבדוק את אפליקציית הייצור שלך עם מפתח 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!