הפתרון הטוב ביותר לאִינְטֶרְנַצִיוֹנָלִיזַצְיָה (i18n) באפליקציות Next.js

איך זה עובד

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

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

המדריך מיועד לאפליקציות Next.js שמשתמשות ב-Pages Router.
אם אתה משתמש ב-App Router, אנא עיין במדריך זה במקום.

שלב 1: התקן ספריית i18n

כדי ליישם בינלאומיות באפליקציית Next.js שלך, נבחר תחילה ספריית i18n. קיימות מספר ספריות פופולריות, כולל next-intl. עם זאת, בדוגמה זו נשתמש ב-TacoTranslate.

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

סיימנו! כעת האפליקציה שלך ב-Next.js תתורגם אוטומטית כשתוסיף מחרוזות כלשהן לרכיב Translate. שים לב שרק סביבות עם הרשאות read/write על מפתח ה-API יוכלו ליצור מחרוזות חדשות לתרגום. אנו ממליצים על סביבה סגורה ומאובטחת לסטייג'ינג שבה תוכל לבדוק את אפליקציית הייצור שלך עם מפתח 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!