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