כיצד ליישם בינאום (i18n) באפליקציית 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: קוד ה-locale המשמש כברירת מחדל כגיבוי. בדוגמה זו נגדיר אותו כ־en עבור אנגלית.
• TACOTRANSLATE_ORIGIN: התיקייה שבה יאוחסנו המחרוזות שלך, כגון כתובת ה-URL של האתר שלך. למידע נוסף על origins, לחץ כאן.

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 מותאם אישית, נוסיף את ה-provider של 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), נשתמש במפתח הסודי read/write של ה-API כדי לוודא שמחרוזות חדשות נשלחות לתרגום.

עד כה הגדרנו את יישום 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 שפות וממהן. התחילו היום!