כיצד ליישם בין־לאומיות (internationalization) ביישום Next.js שמשתמש ב- App Router

בעולם שהולך ומתגלגל לגלובליזציה, זה נעשה חשוב יותר ויותר למפתחי ווב לבנות יישומים שיכולים להתאים למשתמשים ממדינות ותרבויות שונות. אחת הדרכים המרכזיות להשגת זאת היא באמצעות אִינְטֶרנַצִיוֹנָלִיזַצְיָה (i18n), שמאפשרת לך להתאים את היישום שלך לשפות, מטבעות ותבניות תאריך שונות.

במאמר זה, נחקור כיצד להוסיף אִינְטֶרנַצִיוֹנָלִיזַצְיָה ליישום React Next.js שלך, עם רינדור בצד השרת. TL;DR: ראה כאן את הדוגמה המלאה.

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

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

כדי ליישם בינאום (internationalization) באפליקציית 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'; המציין שזו קומפוננטת לקוח.

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

עכשיו, בואו נבנה את הדף הראשון שלנו! צרו קובץ בשם /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 תומך ב-rendering בצד השרת. זה משפר משמעותית את חוויית המשתמש על ידי הצגת תוכן מתורגם מיידית, במקום הבזק של תוכן לא מתורגם בתחילה. בנוסף, אנו יכולים לדלג על בקשות רשת בצד הלקוח, מכיוון שכבר יש לנו את התרגומים הדרושים לעמוד שבו המשתמש צופה.

כדי להגדיר רינדור בצד השרת, צור או ערוך את הקובץ /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!