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