چگونه در یک برنامه 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 در ریشه پروژه خود اضافه کنید.

.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 ها بیشتر بخوانید.

.env

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

مرحله ۳: راه‌اندازی TacoTranslate

برای ادغام TacoTranslate با برنامه خود، باید یک کلاینت با استفاده از کلیدهای API که قبلاً تهیه کرده‌اید ایجاد کنید. به عنوان مثال، یک فایل با نام /tacotranslate-client.js بسازید.

/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 را اضافه خواهیم کرد.

/pages/_app.tsx

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 شروع خواهیم کرد.

/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 دارید.

/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!"/>
}

مرحله ۵: استقرار و تست!

کار تمام است! اکنون وقتی هر رشته‌ای را به یک کامپوننت Translate اضافه کنید، برنامه React شما به‌طور خودکار ترجمه خواهد شد. توجه داشته باشید که فقط محیط‌هایی که دسترسی read/write روی کلید API دارند، قادر خواهند بود رشته‌های جدیدی برای ترجمه ایجاد کنند. توصیه می‌کنیم یک محیط staging بسته و امن داشته باشید که بتوانید برنامه تولید خود را با چنین کلید API ای تست کنید و رشته‌های جدید را پیش از انتشار اضافه کنید. این کار از سرقت کلید API محرمانه شما توسط دیگران جلوگیری می‌کند و همچنین از اضافه شدن رشته‌های جدید و نامرتبط که پروژه ترجمه شما را پرحجم می‌کنند، جلوگیری خواهد کرد.

حتماً نمونه کامل را در پروفایل گیت‌هاب ما بررسی کنید. در آنجا همچنین نمونه‌ای از نحوه انجام این کار با استفاده از App Router خواهید یافت! اگر با هر مشکلی مواجه شدید، لطفاً با ما تماس بگیرید، و ما بسیار خوشحال خواهیم شد که کمک کنیم.

با TacoTranslate می‌توانید برنامه‌های React خود را به طور خودکار و سریع به بیش از ۷۵ زبان مختلف بومی‌سازی کنید. همین امروز شروع کنید!