نحوه پیادهسازی بینالمللیسازی در یک برنامه 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
: کد محلی پیشفرض (fallback). در این مثال، آن را رویen
برای زبان انگلیسی تنظیم میکنیم.TACOTRANSLATE_ORIGIN
: «پوشه»ای که رشتههای شما در آن ذخیره خواهند شد، مانند آدرس وبسایت شما. برای اطلاعات بیشتر در مورد مبداها اینجا را بخوانید.
TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com
مرحله 3: راهاندازی 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
بهطور پیشفرض روی 60 تنظیم شده است تا ترجمههای شما بهروز بمانند.
برای استفاده از هر یک از این توابع در یک صفحه، فرض کنیم فایل صفحهای مانند /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 مخفی شما توسط دیگران جلوگیری میکند و همچنین از احتمال افزایش بیش از حد حجم پروژهٔ ترجمهتان بهخاطر اضافه شدن رشتههای جدید و نامرتبط پیشگیری خواهد کرد.
حتماً نمونهٔ کامل را در صفحهٔ GitHub ما مشاهده کنید. در آنجا همچنین نمونهای از نحوهٔ انجام این کار با استفاده از App Router خواهید یافت! اگر با هر مشکلی مواجه شدید، دریغ نکنید و با ما تماس بگیرید، ما با کمال میل کمک خواهیم کرد.
TacoTranslate به شما امکان میدهد برنامههای React خود را بهطور خودکار و سریع از/به بیش از ۷۵ زبان بومیسازی کنید. همین امروز شروع کنید!