چگونه بینالمللیسازی را در یک برنامه Next.js که از App Router استفاده میکند، پیادهسازی کنیم
اپلیکیشن React خود را قابل دسترستر سازید و با جهانیسازی (i18n) به بازارهای جدید دست یابید.
با جهانیتر شدن جهان، برای توسعهدهندگان وب روز به روز اهمیت بیشتری پیدا میکند که برنامههایی بسازند که بتوانند به کاربران از کشورهای مختلف و فرهنگهای متفاوت خدمترسانی کنند. یکی از راههای کلیدی برای رسیدن به این هدف، بینالمللیسازی (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
: «پوشهای» که رشتههای شما در آن ذخیره خواهند شد، مانند URL وبسایت شما. اینجا درباره منشاها بیشتر بخوانید.
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';
که نشان میدهد این یک کامپوننت کلاینت است.
با آماده شدن فراهمکنندهی زمینه، یک فایل به نام /app/[locale]/layout.tsx
ایجاد کنید، که طرح ریشهای در برنامهی ما است. توجه داشته باشید که این مسیر دارای یک پوشه است که از 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
)، از کلید 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
را مطابق با مستندات میانافزار Next.js تنظیم کردهاید.
در سمت کلاینت، شما میتوانید کوکی locale
را تغییر دهید تا زبان مورد علاقه کاربر را تنظیم کنید. لطفاً برای دریافت ایدهها در مورد چگونگی انجام این کار، به کد نمونه کامل مراجعه کنید!
گام ۵: استقرار و آزمایش!
ما کار را تمام کردیم! اکنون برنامه 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!