איך ליישם בינלאומיות (i18n) ביישום 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 וה-mפתח 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, זהו ה-root 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 מוודא שכל קודי ה-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 הציבורי. אם אנחנו בסביבת פיתוח מקומית, בדיקה או סטייג'ינג (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.

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