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

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

במדריך זה נלמד כיצד להוסיף בינלאומיות (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 וה-mפתח 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 של האתר שלך. קרא/י עוד על מקורות כאן.

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), נשתמש במפתח ה-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 שפות ולהיפך. התחילו היום!