כיצד ליישם בינאום (i18n) ביישום 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: קוד ברירת המחדל (שפת גיבוי). בדוגמה זו, נקבע אותו ל־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 בקרוב.

יצירת ה-client בקובץ נפרד מקלה על השימוש בו שוב מאוחר יותר. כעת, באמצעות קובץ מותאם אישית /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 יוכלו ליצור מחרוזות חדשות לתרגום. אנו ממליצים על סביבת סטייג' סגורה ומאובטחת שבה ניתן לבדוק את גרסת הייצור של האפליקציה עם מפתח API כזה, ולהוסיף מחרוזות חדשות לפני העלייה לאוויר. זה ימנע מאחרים לגנוב את מפתח ה‑API הסודי שלך, ובכך ימנע גם ניפוח אפשרי של פרויקט התרגום שלך כתוצאה מהוספת מחרוזות חדשות ובלתי רלוונטיות.

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

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