چگونه بینالمللیسازی را در یک برنامه Next.js که از Pages Router استفاده میکند، پیادهسازی کنیم؟
اپلیکیشن React خود را با بومیسازی (i18n) قابل دسترستر کنید و به بازارهای جدید دست یابید.
با جهانیتر شدن دنیا، ساخت برنامههایی که بتوانند نیازهای کاربران از کشورهای مختلف و فرهنگهای گوناگون را پاسخ دهند، برای توسعهدهندگان وب اهمیت فزایندهای یافته است. یکی از روشهای کلیدی برای رسیدن به این هدف، بینالمللیسازی (i18n) است که به شما امکان میدهد برنامه خود را به زبانها، ارزها و قالبهای تاریخ مختلف تطبیق دهید.
در این آموزش، نحوه افزودن بینالمللیسازی به برنامه React Next.js خود با رندرینگ سمت سرور را بررسی خواهیم کرد. TL;DR: نمونه کامل را اینجا ببینید.
این راهنما برای برنامههای Next.js است که از Pages Router استفاده میکنند.
اگر از App Router استفاده میکنید، لطفاً بهجای آن این راهنما را ببینید.
مرحله ۱: نصب یک کتابخانه i18n
برای پیادهسازی بینالمللیسازی (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
: «پوشهای» که رشتههای شما در آن ذخیره خواهند شد، مانند آدرس وبسایت شما. برای اطلاعات بیشتر درباره 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 را نمایش میدهد. اگر در یک محیط محلی، تست یا استیجینگ باشیم (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
اضافه کنید. توجه داشته باشید که تنها محیطهایی که روی کلید API مجوز read/write
را دارند قادر خواهند بود رشتههای جدیدی برای ترجمه ایجاد کنند. توصیه میکنیم یک محیط staging بسته و امن داشته باشید تا بتوانید برنامهٔ production خود را با چنین کلید API آزمایش کنید و قبل از انتشار، رشتههای جدید را اضافه نمایید. این کار از سرقت کلید API محرمانهٔ شما جلوگیری میکند و همچنین از پرشدن پروژهٔ ترجمهتان با رشتههای جدید و نامرتبط جلوگیری میکند.
حتماً مثال کامل را در پروفایل گیتهاب ما بررسی کنید. آنجا همچنین یک مثال خواهید یافت که چگونه این کار را با استفاده از App Router انجام دهید! اگر با هر مشکلی مواجه شدید، لطفاً تماس بگیرید و با کمال میل کمک خواهیم کرد.
TacoTranslate به شما امکان میدهد برنامههای React خود را بهطور خودکار به بیش از ۷۵ زبان و از آنها بومیسازی کنید. هماکنون شروع کنید!