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

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

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

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

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

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

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

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

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

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

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

שלב 3: הגדרת TacoTranslate

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

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

ודאו ללעיין בדוגמה המלאה בפרופיל שלנו ב-GitHub. שם תוכלו גם למצוא דוגמה כיצד לעשות זאת באמצעות Pages Router ! אם תיתקלו בבעיות כלשהן, אל תהססו ליצור קשר, ונשמח מאוד לעזור לכם.

TacoTranslate מאפשרת לכם לתרגם את יישומי React שלכם אוטומטית ומהר לכל שפה ולהפך. התחילו עוד היום!