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

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, הפריסה השורשית שבהחלט שלנו. שים לב कि מסלול זה מכיל תיקיה המשתמשת ב- 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 בהתאם ל-תיעוד ה-Next.js Middleware.

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

שלב 5: הפעל וערוך בדיקות!

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

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

TacoTranslate מאפשר לכם לאתר אוטומטית את אפליקציות ה-React שלכם במהירות לכל שפה וממנה. התחילו היום!