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

בתוך ממשק ה-UI של 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!