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

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

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

TacoTranslate מאפשרת לכם לתרגם את אפליקציות React שלכם אוטומטית במהירות ליותר מ-75 שפות ולהפך. התחילו היום!