نحوه پیادهسازی بینالمللیسازی در یک اپلیکیشن Next.js که از App Router استفاده میکند
با جهانیسازی (i18n) برنامه React خود را دسترسپذیرتر کنید و به بازارهای جدید دست یابید.
با جهانی شدن بیشتر دنیا، برای توسعهدهندگان وب اهمیت بیشتری پیدا میکند که برنامههایی بسازند که بتوانند کاربران از کشورهای مختلف و فرهنگهای گوناگون را پوشش دهند. یکی از راههای کلیدی برای دستیابی به این هدف، بینالمللیسازی (i18n) است که به شما این امکان را میدهد برنامه خود را به زبانها، ارزها و فرمتهای تاریخ مختلف سازگار کنید.
در این مقاله، نحوه افزودن بینالمللیسازی به برنامه React Next.js خود با رندر سمت سرور را بررسی خواهیم کرد. TL;DR: نمونه کامل را در اینجا ببینید.
این راهنما برای برنامههای Next.js که از App Router استفاده میکنند مناسب است.
اگر از Pages Router استفاده میکنید، به جای آن این راهنما را ببینید.
مرحله ۱: نصب یک کتابخانه i18n
برای پیادهسازی بینالمللیسازی در برنامه Next.js خود، ابتدا یک کتابخانه i18n انتخاب میکنیم. چندین کتابخانه محبوب وجود دارد، از جمله next-intl. اما در این مثال، ما از TacoTranslate استفاده خواهیم کرد.
TacoTranslate به طور خودکار رشتههای شما را با استفاده از هوش مصنوعی پیشرفته به هر زبان ترجمه میکند و شما را از مدیریت خستهکننده فایلهای JSON آزاد میکند.
بیایید آن را با استفاده از npm در ترمینال خود نصب کنیم:
npm install tacotranslate
مرحله ۲: یک حساب رایگان در 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
: «پوشه» ای که رشتههای شما در آن ذخیره خواهند شد، مانند آدرس وبسایت شما. برای اطلاعات بیشتر درباره origins اینجا را بخوانید.
TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com
مرحله ۳: تنظیم 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';
که نشان میدهد این یک کامپوننت کلاینت است.
حال که context provider آماده است، یک فایل به نام /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 میگوید پس از ۶۰ ثانیه صفحه را دوباره بسازد و ترجمههای شما را بهروز نگه دارد.
مرحله ۴: پیادهسازی رندر سمت سرور
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 عمومی را نمایش میدهد. اگر در یک محیط محلی، آزمایشی یا مرحله آزمایشی هستیم (isProduction
is false
)، از کلید مخفی read/write
API استفاده خواهیم کرد تا اطمینان حاصل شود رشتههای جدید برای ترجمه ارسال میشوند.
برای اطمینان از عملکرد صحیح مسیردهی و ریدایرکت، باید فایل /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
را تغییر دهید تا زبان مورد علاقه کاربر را تنظیم کنید. لطفاً برای دریافت ایده درباره نحوه انجام این کار، به نمونه کد کامل مراجعه کنید!
مرحله ۵: استقرار و آزمایش کنید!
کار ما تمام است! برنامه React شما اکنون بهصورت خودکار ترجمه خواهد شد زمانی که هر رشتهای را به یک کامپوننت Translate
اضافه کنید. توجه داشته باشید که فقط محیطهایی که دسترسی read/write
روی کلید API دارند قادر خواهند بود رشتههای جدیدی برای ترجمه ایجاد کنند. توصیه میکنیم یک محیط staging بسته و ایمن داشته باشید که در آن بتوانید برنامه تولید خود را با چنین کلید 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!