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

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

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

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