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