איך ליישם בינלאומיות באפליקציית Next.js שמשתמשת ב-App Router
הפוך את אפליקציית React שלך ליותר נגישה והגעה לשווקים חדשים עם הבינלאומיות (i18n).
בעולם שהופך לגלובלי יותר ויותר, חשוב יותר ויותר למפתחי ווב לבנות יישומים שיכולים לענות על צרכים של משתמשים ממדינות ותרבויות שונות. אחד האמצעים המרכזיים להשגת זאת הוא דרך אִינְטֶרְנַצִיוֹנָלִיזַצְיָה (i18n), שמאפשרת להתאים את היישום שלך לשפות, מטבעות ותבניות תאריכים שונות.
במאמר זה, נחקור כיצד להוסיף אִינְטֶרְנַצִיוֹנָלִיזַצְיָה ליישום React Next.js שלך, עם רינדור בצד השרת. TL;DR: ראה את הדוגמה המלאה כאן.
המדריך הזה מיועד ליישומי Next.js שמשתמשים ב-App Router.
אם אתם משתמשים ב-Pages 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
: ה"תקייה" בה יאוחסנו המחרוזות שלך, כגון כתובת האתר שלך. קרא עוד על מקורות כאן.
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 תומך ב־server side rendering. זה משפר משמעותית את חוויית המשתמש על ידי הצגת תוכן מתורגם מיידית, במקום הבזק של תוכן שלא תורגם תחילה. בנוסף, אנחנו יכולים לדלג על בקשות רשת בצד הלקוח, משום שכבר יש לנו את התרגומים הדרושים לדף שהמשתמש צופה בו.
כדי להגדיר רינדור בצד השרת, צור או שנה את הקובץ /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 יוכלו ליצור מחרוזות חדשות לתרגום. אנו ממליצים על סביבה סגורה ומאובטחת של סטייג'ינג שבה תוכל לבדוק את אפליקציית הייצור שלך עם מפתח 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!