چگونه در یک برنامه 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
)، از کلید API مخفی read/write
استفاده میکنیم تا اطمینان حاصل شود که رشتههای جدید برای ترجمه ارسال میشوند.
تا کنون، ما تنها فهرستی از زبانهای پشتیبانی شده را در برنامه 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 باشند، قادر خواهند بود رشتههای جدید برای ترجمه ایجاد کنند. ما توصیه میکنیم یک محیط staging بسته و ایمن داشته باشید که بتوانید برنامهٔ تولیدی خود را با چنین کلید API تست کنید و قبل از عرضهٔ نهایی رشتههای جدید اضافه کنید. این کار مانع از آن میشود که کسی کلید API محرمانه شما را به سرقت ببرد و احتمالاً پروژهٔ ترجمهٔ شما را با اضافه کردن رشتههای جدید و نامرتبط بیش از حد شلوغ کند.
مطمئن شوید که نمونه کامل را در پروفایل GitHub ما بررسی کنید. در آنجا همچنین نمونهای از چگونگی انجام این کار با استفاده از App Router خواهید یافت! اگر با مشکلی مواجه شدید، بهصورت آزادانه با ما تماس بگیرید
TacoTranslate به شما این امکان را میدهد که برنامههای React خود را بهطور خودکار و سریع به هر زبان و از هر زبان بومیسازی کنید. امروز شروع کنید!