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

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

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

המדריך הזה מיועד ליישומי Next.js המשתמשים ב-Pages Router.
אם אתם משתמשים ב-App 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 והמפתח 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 באפליקציה שלך, יש ליצור 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 שפות ובחזרה. התחילו היום!