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