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

איך זה עובד

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

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

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

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