הפתרון הטוב ביותר לבינאום (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: קוד ברירת המחדל לשפה חלופית. בדוגמה זו, נגדיר אותו כ־en עבור אנגלית.
• TACOTRANSLATE_ORIGIN: ה"תוֹקֶן" בו יאוחסנו המחרוזות שלך, כגון כתובת האתר שלך. קרא/י עוד על תוֹקַנים כאן.

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

ודאו לבדוק את הדוגמה המלאה בפרופיל שלנו ב-GitHub. שם, תוכלו גם למצוא דוגמה כיצד לעשות זאת באמצעות App Router ! אם תיתקלו בבעיות, אל תהססו ליצור קשר, ונשמח מאוד לעזור לכם.

TacoTranslate מאפשרת לכם לתרגם באופן אוטומטי את יישומי React שלכם במהירות לכל שפה וממנה. התחילו עוד היום!