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

בצד הלקוח ניתן לשנות את העוגיה 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!