כיצד ליישם בינלאומיות (i18n) ביישום 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: קוד ה‑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), נשתמש במפתח הסודי 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 שפות וממהן. התחילו היום!