כיצד ליישם אינטרנציונליזציה באפליקציית Next.js שמשתמשת בPages Router

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

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

מדריך זה מיועד ליישומי Next.js המשתמשים ב- Pages Router.
אם אתם משתמשים ב- App 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: קוד ברירת המחדל לגיבוי. בדוגמה זו נגדיר אותו כ־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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

נגדיר אוטומטית את TACOTRANSLATE_API_KEY בקרוב.

יצירת הלקוח בקובץ נפרד מקלה על השימוש בו שוב מאוחר יותר. כעת, באמצעות קובץ מותאם אישית /pages/_app.tsx, נוסיף את הספק של TacoTranslate.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

אם כבר יש לכם pageProps ו-_app.tsx מותאמים אישית, הרחיבו בבקשה את ההגדרה כך שתכלול את התכונות והקוד שניתנו לעיל.

שלב 4: יישום רינדור בצד השרת

TacoTranslate מאפשר רינדור בצד השרת עבור התרגומים שלך. זה משפר משמעותית את חוויית המשתמש על ידי הצגת תוכן מתורגם מיידית, במקום הבהוב של תוכן לא מתורגם תחילה. בנוסף, ניתן לדלג על בקשות רשת בצד הלקוח, כי כבר יש לנו את כל התרגומים הדרושים.

נתחיל ביצירה או בשינוי של /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

שנה את הבדיקה של isProduction כך שתתאים להגדרות שלך. אם true, TacoTranslate יציג את מפתח ה-API הציבורי. אם אנחנו בסביבה מקומית, בדיקה או סטייג'ינג (isProduction is false), נשתמש במפתח ה-API הסודי read/write כדי לוודא שמחרוזות חדשות נשלחות לתרגום.

עד כה הגדרנו באפליקציית Next.js רק רשימה של שפות נתמכות. הדבר הבא שנעשה הוא לאחזר תרגומים לכל הדפים שלך. כדי לעשות זאת, תשתמש באחת מהפונקציות getTacoTranslateStaticProps או getTacoTranslateServerSideProps בהתאם לדרישותיך.

פונקציות אלה מקבלות שלושה ארגומנטים: אובייקט אחד Next.js Static Props Context, תצורה עבור TacoTranslate, ותכונות אופציונליות של Next.js. שים לב ש‑revalidate ב־getTacoTranslateStaticProps מוגדר ל־60 כברירת מחדל, כדי שהתירגומים שלך יישארו מעודכנים.

כדי להשתמש באחת מהפונקציות בדף, נניח שיש לך קובץ דף כמו /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

כעת אתה אמור להיות מסוגל להשתמש ברכיב Translate כדי לתרגם מחרוזות בתוך כל רכיבי ה-React שלך.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

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

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

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

TacoTranslate מאפשרת לתמוך בתרגום אוטומטי של אפליקציות ה‑React שלכם ליותר מ‑75 שפות ובחזרה. התחילו היום!