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