چگونه بینالمللیسازی را در یک برنامه 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 وبسایت شما. برای اطلاعات بیشتر در مورد 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
را مطابق با مستندات میانافزار Next.js تنظیم کنید.
در سمت کلاینت، میتوانید کوکی locale
را تغییر دهید تا زبان ترجیحی کاربر را تغییر دهید. برای ایدهها در مورد چگونگی انجام این کار، لطفاً به کد نمونه کامل مراجعه کنید!
مرحله ۵: استقرار و آزمایش کنید!
کار ما تمام شد! حالا برنامه React شما به صورت خودکار ترجمه خواهد شد هر زمان که هر رشتهای را به یک کامپوننت Translate
اضافه کنید. توجه داشته باشید که فقط محیطهایی که دسترسیهای read/write
روی کلید API دارند، قادر خواهند بود رشتههای جدید برای ترجمه ایجاد کنند. توصیه میکنیم یک محیط استیجینگ بسته و ایمن داشته باشید که بتوانید برنامه تولیدی خود را با چنین کلید API آزمایش کنید و قبل از انتشار، رشتههای جدید اضافه کنید. این کار از دزدیده شدن کلید API مخفی شما جلوگیری میکند و همچنین از احتمال افزایش بیرویه پروژه ترجمه بهوسیله اضافه کردن رشتههای جدید و نامرتبط جلوگیری خواهد کرد.
حتماً به مثال کامل در پروفایل گیتهاب ما نگاهی بیندازید. همچنین آنجا مثالی از چگونگی انجام این کار با استفاده از Pages Router خواهید یافت! اگر با هر مشکلی مواجه شدید، بدون تردید با ما تماس بگیرید، و ما با کمال میل کمک خواهیم کرد.
TacoTranslate به شما اجازه میدهد برنامههای React خود را بهصورت خودکار و سریع به هر زبان و از هر زبان بومیسازی کنید. امروز شروع کنید!