چگونه بینالمللیسازی را در یک برنامه 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
: «پوشهای» که رشتههای شما در آن ذخیره میشوند، مانند آدرس وبسایت شما. برای اطلاعات بیشتر درباره 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 خود را به سرعت به هر زبانی و از هر زبانی بومیسازی کنید. امروز شروع کنید!