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

יצירת ה-client בקובץ נפרד מקלה על השימוש בו שוב בהמשך. 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 מוודא שכל קודי המקומיות (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 הציבורי. אם אנחנו בסביבה מקומית, בסביבת בדיקה או בסביבת staging (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!