הפתרון הטוב ביותר לאינטרנציונליזציה (i18n) באפליקציות Next.js

איך זה עובד

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

סיימנו! אפליקציית Next.js שלך תתורגם כעת אוטומטית כאשר תוסיף כל מחרוזת לרכיב Translate. שים לב שרק סביבות שיש להן הרשאות read/write על מפתח ה-API יוכלו ליצור מחרוזות חדשות לתרגום. אנו ממליצים להחזיק סביבת בדיקות (staging) סגורה ומאובטחת שבה תוכל/תוכלי לבדוק את יישום הייצור שלך עם מפתח API כזה ולהוסיף מחרוזות חדשות לפני העלייה לאוויר. זה ימנע מאחרים לגנוב את מפתח ה-API הסודי שלך, וכן ימנע נפיחה של פרויקט התרגום כתוצאה מהוספת מחרוזות חדשות שאין להן קשר.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!