כיצד ליישם אינטרנציונליזציה באפליקציית Next.js שמשתמשת ב־App Router
הפכו את אפליקציית ה-React שלכם לנגישה יותר וכבשו שווקים חדשים עם הבינלאומיות (i18n).
בעולם שהולך והופך לגלובלי יותר, חשיבותה של בניית יישומים שיכולים לשרת משתמשים ממדינות ותרבויות שונות הולכת וגדלה עבור מפתחי האינטרנט. אחת הדרכים המרכזיות להשיג זאת היא באמצעות בינאומיות (internationalization, i18n), שמאפשרת לך להתאים את היישום לשפות, למטבעות ולפורמטים של תאריכים שונים.
במאמר זה נבחן כיצד להוסיף בינאומיות ליישום ה-React Next.js שלך, כולל רינדור בצד השרת. TL;DR: ראה את הדוגמה המלאה כאן.
המדריך הזה מיועד ליישומי Next.js שמשתמשים ב-App Router.
אם אתם משתמשים ב-Pages 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_IS_PRODUCTION === 'true'
? process.env.TACOTRANSLATE_PROJECT_LOCALE
: undefined,
});
module.exports = tacoTranslate;
בהמשך נגדיר אוטומטית את TACOTRANSLATE_API_KEY
ואת TACOTRANSLATE_PROJECT_LOCALE
.
יצירת הלקוח בקובץ נפרד עושה את זה קל לשימוש חוזר מאוחר יותר. getLocales
היא רק פונקציית עזר עם טיפול מובנה בשגיאות. עכשיו, צור קובץ בשם /app/[locale]/tacotranslate.tsx
, שבו נממש את ספק TacoTranslate
.
'use client';
import React, {type ReactNode} from 'react';
import {
type TranslationContextProperties,
TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';
export default function TacoTranslate({
locale,
origin,
localizations,
children,
}: TranslationContextProperties & {
readonly children: ReactNode;
}) {
return (
<ImportedTacoTranslate
client={tacoTranslateClient}
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</ImportedTacoTranslate>
);
}
שימו לב ל-'use client';
המציין שזהו קומפוננטת לקוח.
כעת שהספק הקונטקסט מוכן לשימוש, צור קובץ בשם /app/[locale]/layout.tsx
, שהוא ה-layout הראשי באפליקציה שלנו. שים לב שדרך זו מכילה תיקייה שמשתמשת ב- Dynamic Routes, כאשר [locale]
הוא הפרמטר הדינמי.
import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';
export async function generateStaticParams() {
const locales = await tacoTranslateClient.getLocales();
return locales.map((locale) => ({locale}));
}
type RootLayoutParameters = {
readonly params: Promise<{locale: Locale}>;
readonly children: ReactNode;
};
export default async function RootLayout({params, children}: RootLayoutParameters) {
const {locale} = await params;
const origin = process.env.TACOTRANSLATE_ORIGIN;
const localizations = await tacoTranslateClient.getLocalizations({
locale,
origins: [origin /* , other origins to fetch */],
});
return (
<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
<body>
<TacoTranslate
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</TacoTranslate>
</body>
</html>
);
}
הדבר הראשון שצריך לשים לב אליו כאן הוא שאנו משתמשים בפרמטר Dynamic Route
שלנו [locale]
כדי להביא תרגומים לשפה זו. בנוסף, generateStaticParams
מוודא שכל קודי השפות שהפעלת עבור הפרויקט שלך מוצגים מראש.
עכשיו, בואו נבנה את הדף הראשון שלנו! צרו קובץ בשם /app/[locale]/page.tsx
.
import React from 'react';
import {Translate} from 'tacotranslate/react';
export const revalidate = 60;
export default async function Page() {
return (
<Translate string="Hello, world!" />
);
}
שימו לב למשתנה revalidate
שמורה ל-Next.js לבנות מחדש את העמוד אחרי 60 שניות, ולשמור על התרגומים שלכם מעודכנים.
שלב 4: יישום רינדור בצד השרת
TacoTranslate תומך ביצירת דפי שרת. זה משפר משמעותית את חוויית המשתמש על ידי הצגת תוכן מתורגם מיידית, במקום הבזק של תוכן לא מתורגם תחילה. בנוסף, אנו יכולים לדלג על בקשות רשת מצד הלקוח, כיוון שכבר יש לנו את התרגומים הדרושים לעמוד שהמשתמש צופה בו.
כדי להגדיר רינדור בצד השרת, צור או ערוך את הקובץ /next.config.js
:
const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');
module.exports = async () => {
const config = await withTacoTranslate(
{},
{
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'),
}
);
// NOTE: Remove i18n from config when using the app router
return {...config, i18n: undefined};
};
שנה את הבדיקה של isProduction
כדי להתאים להגדרות שלך. אם true
, TacoTranslate יציג את מפתח ה-API הציבורי. אם אנחנו בסביבת פיתוח מקומית, בדיקה או סביבה למעבר (staging) (isProduction
is false
), נשתמש במפתח ה-API הסודי read/write
כדי לוודא שמחרוזות חדשות נשלחות לתרגום.
כדי לוודא שניווט והפניות יפעלו כמצופה, נצטרך ליצור קובץ בשם /middleware.ts
. באמצעות Middleware, נוכל להפנות משתמשים לדפים המוצגים בשפת ההעדפה שלהם.
import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';
export const config = {
matcher: ['/((?!api|_next|favicon.ico).*)'],
};
export async function middleware(request: NextRequest) {
return tacoTranslateMiddleware(tacoTranslate, request);
}
ודא להגדיר את matcher
בהתאם להתיעוד של Middleware ב-Next.js.
בצד הלקוח, ניתן לשנות את העוגיה locale
כדי לשנות מהי השפה המועדפת על המשתמש. אנא עיין ב-קוד הדוגמה המלא לרעיונות כיצד לעשות זאת!
שלב 5: פרוס ונסה!
סיימנו! כעת האפליקציה שלך ב-React תתורגם אוטומטית כאשר תוסיף מחרוזות חדשות לרכיב Translate
. שים לב שרק סביבות שיש להן הרשאות read/write
במפתח ה-API יוכלו ליצור מחרוזות חדשות לתרגום. אנו ממליצים להחזיק סביבה סגורה ומאובטחת של staging שבה תוכל לבדוק את אפליקציית ה-production שלך עם מפתח 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 Pages 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!