כיצד ליישם בין-לאומיות ביישום 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 מתרגם אוטומטית את המחרוזות שלך לכל שפה באמצעות בינה מלאכותית מתקדמת, ומשחרר אותך מהניהול המייגע של קבצי 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: קוד הלוקל (locale) המוחזר כברירת מחדל. בדוגמה זו, נגדיר אותו כ-en עבור אנגלית.
• TACOTRANSLATE_ORIGIN: ה"תקייה" שבה יאוחסנו המחרוזות שלך, כגון כתובת האתר שלך. קרא עוד על אודות origins כאן.

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

שלב 3: הגדרת TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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. זה משפר במידה רבה את חוויית המשתמש על ידי הצגת תוכן מתורגם מיד, במקום הבזק של תוכן לא מתורגם בתחילה. בנוסף, אנו יכולים לדלג על בקשות רשת בצד הלקוח, מכיוון שכבר יש לנו את התרגומים הדרושים לעמוד שהמשתמש צופה בו.

כדי להגדיר רינדור בצד השרת, צור או שנה את /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 בהתאם ל-התיעוד של Next.js Middleware.

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

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

השלמנו! אפליקציית ה-React שלך תתורגם אוטומטית כשתוסיף כל מחרוזת לרכיב Translate. שים לב שרק סביבות עם הרשאות read/write על מפתח ה-API יוכלו ליצור מחרוזות חדשות לתרגום. אנו ממליצים על סביבה סגורה ומאובטחת של staging שבה תוכל לבדוק את אפליקציית הייצור שלך עם מפתח API כזה, ולהוסיף מחרוזות חדשות לפני העלאה לאוויר. זה ימנע מאחרים לגנוב את מפתח ה-API הסודי שלך, ואולי גם למנוע נפיחות לא רצויה בפרויקט התרגום שלך באמצעות הוספת מחרוזות חדשות ובלתי קשורות.

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

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