چگونه بینالمللیسازی را در یک برنامه Next.js که از Pages Router استفاده میکند، پیادهسازی کنیم
برنامه React خود را بیشتر قابل دسترس کنید و با بینالمللیسازی (i18n) به بازارهای جدید دست یابید.
با جهانیتر شدن دنیا، برای توسعهدهندگان وب ساخت برنامههایی که بتوانند به کاربران از کشورهای مختلف و فرهنگهای متفاوت پاسخ دهند، اهمیت بیشتری پیدا میکند. یکی از راههای کلیدی برای رسیدن به این هدف، بینالمللیسازی (i18n) است که به شما امکان میدهد برنامهتان را با زبانها، ارزها، و فرمتهای تاریخی مختلف سازگار کنید.
در این آموزش، نحوه افزودن بینالمللیسازی به برنامه React Next.js خود با رندر سمت سرور را بررسی خواهیم کرد. TL;DR: نمونه کامل را اینجا ببینید.
این راهنما برای برنامههای Next.js است که از Pages Router استفاده میکنند.
اگر از App 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_DEFAULT_LOCALE ?? '',
});
module.exports = tacoTranslate;
ما به طور خودکار به زودی TACOTRANSLATE_API_KEY
را تعریف خواهیم کرد.
ایجاد کلاینت در یک فایل جداگانه استفاده مجدد آن را در آینده آسانتر میکند. اکنون، با استفاده از یک فایل سفارشی /pages/_app.tsx
, ما ارائهدهنده TacoTranslate
را اضافه خواهیم کرد.
import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';
type PageProperties = {
origin: Origin;
locale: Locale;
locales: Locale[];
localizations: Localizations;
};
export default function App({Component, pageProps}: AppProps<PageProperties>) {
const {origin, locale, locales, localizations} = pageProps;
return (
<TacoTranslate
client={tacoTranslate}
origin={origin}
locale={locale}
localizations={localizations}
>
<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
<Component {...pageProps} />
</TacoTranslate>
);
}
اگر شما قبلاً pageProps
و _app.tsx
سفارشی دارید، لطفاً تعریف را با ویژگیها و کدهای ذکر شده در بالا گسترش دهید.
مرحله ۴: پیادهسازی رندرینگ سمت سرور
TacoTranslate اجازه میدهد تا ترجمههای شما به صورت سمت سرور رندر شوند. این موضوع تجربه کاربری را به شدت بهبود میبخشد زیرا محتویات ترجمه شده را فوراً نمایش میدهد، به جای اینکه ابتدا یک لحظه محتویات ترجمه نشده را نشان دهد. علاوه بر این، میتوانیم درخواستهای شبکه را در سمت کلاینت نادیده بگیریم، چون قبلاً همه ترجمههای مورد نیاز را داریم.
ما با ایجاد یا اصلاح /next.config.js
شروع خواهیم کرد.
const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');
module.exports = async () => {
const config = {};
return withTacoTranslate(config, {
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'),
});
};
تنظیم isProduction
را مطابق با راهاندازی خود تغییر دهید. اگر true
بود، TacoTranslate کلید API عمومی را نمایش خواهد داد. اگر ما در یک محیط محلی، آزمایشی، یا استیجینگ باشیم (isProduction
is false
)، از کلید مخفی read/write
API استفاده خواهیم کرد تا مطمئن شویم رشتههای جدید برای ترجمه ارسال میشوند.
تا همین حالا، ما فقط برنامه Next.js را با لیستی از زبانهای پشتیبانیشده تنظیم کردهایم. کاری که بعدی انجام خواهیم داد، دریافت ترجمهها برای تمام صفحات شما است. برای این کار، بسته به نیازهای خود، از یکی از توابع getTacoTranslateStaticProps
یا getTacoTranslateServerSideProps
استفاده خواهید کرد.
این توابع سه آرگومان میگیرند: یک شیء Next.js Static Props Context, پیکربندی برای TacoTranslate، و ویژگیهای اختیاری Next.js. توجه داشته باشید که مقدار revalidate
در getTacoTranslateStaticProps
به صورت پیشفرض روی ۶۰ تنظیم شده است، تا ترجمههای شما بهروز بمانند.
برای استفاده از هر کدام از این توابع در یک صفحه، فرض کنیم شما یک فایل صفحهای مانند /pages/hello-world.tsx
دارید.
import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';
export async function getStaticProps(context) {
return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}
export default function Page() {
return <Translate string="Hello, world!"/>;
}
اکنون باید بتوانید از جزء Translate
برای ترجمه رشتهها در تمام اجزای React خود استفاده کنید.
import {Translate} from 'tacotranslate/react';
function Component() {
return <Translate string="Hello, world!"/>
}
مرحله ۵: استقرار و آزمایش کنید!
ما تمام کردیم! برنامه React شما اکنون به صورت خودکار ترجمه خواهد شد هنگامی که هر رشتهای را به یک کامپوننت Translate
اضافه کنید. توجه داشته باشید که فقط محیطهایی که دسترسی read/write
در کلید API دارند قادر خواهند بود رشتههای جدیدی برای ترجمه ایجاد کنند. ما توصیه میکنیم که یک محیط آزمایشی بسته و امن داشته باشید که در آن بتوانید برنامه تولیدی خود را با چنین کلید API تست کنید و رشتههای جدید را قبل از انتشار اضافه نمایید. این کار از سرقت کلید API محرمانه شما توسط هر کسی جلوگیری میکند و همچنین از افزایش ناخواسته و نامرتبط پروژه ترجمه شما جلوگیری خواهد کرد.
حتماً مثال کامل را بررسی کنید در پروفایل گیتهاب ما. در آنجا، همچنین نمونهای از نحوه انجام این کار با استفاده از App Router پیدا خواهید کرد! اگر با مشکلی مواجه شدید، لطفاً آزادانه تماس بگیرید، و ما خوشحال خواهیم شد که کمک کنیم.
TacoTranslate به شما این امکان را میدهد که برنامههای React خود را به طور خودکار و به سرعت به بیش از ۷۵ زبان محلیسازی کنید. امروز شروع کنید!