כיצד ליישם בינלאומיות באפליקציית Next.js המשתמשת ב-Pages Router

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

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

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

שלב 1: התקן ספריית i18n

כדי לממש אינטרנציונליזציה באפליקציית Next.js שלך, נבחר תחילה ספריית i18n. קיימות מספר ספריות פופולריות, כולל next-intl. עם זאת, בדוגמה זו נשתמש ב-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 של האתר שלך. למידע נוסף על Origins לחץ כאן.

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: פרוס ובדוק!

סיימנו! אפליקציית React שלך תתורגם אוטומטית ברגע שתוסיף מחרוזות כלשהן לרכיב Translate. שים לב שרק סביבות עם הרשאות read/write על מפתח ה-API יוכלו ליצור מחרוזות חדשות לתרגום. אנו ממליצים להחזיק בסביבת staging סגורה ומאובטחת שבה תוכל לבדוק את האפליקציה שלך בסביבת הייצור עם מפתח API כזה, ולהוסיף מחרוזות חדשות לפני העלייה לאוויר. זה ימנע מאחרים לגנוב את מפתח ה-API הסודי שלך, ועלול למנוע נפיחות בפרויקט התרגום שלך כתוצאה מהוספת מחרוזות חדשות ובלתי קשורות.

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

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