كيفية تنفيذ التدويل في تطبيق Next.js الذي يستخدم App Router

مع ازدياد العولمة في العالم، يصبح من المهم بشكل متزايد لمطوري الويب بناء تطبيقات تلبي احتياجات المستخدمين من مختلف الدول والثقافات. واحدة من الطرق الرئيسية لتحقيق ذلك هي من خلال التدويل (i18n)، الذي يسمح لك بتكييف تطبيقك ليدعم لغات مختلفة، وعملات مختلفة، وصيغ تواريخ متنوعة.

في هذه المقالة، سوف نستعرض كيفية إضافة التدويل إلى تطبيقك React Next.js، مع التقديم من جانب الخادم. TL;DR: راجع المثال الكامل هنا.

هذا الدليل مخصص لتطبيقات Next.js التي تستخدم App Router.
إذا كنت تستخدم Pages Router, فراجع هذا الدليل بدلاً من ذلك.

الخطوة 1: تثبيت مكتبة i18n

لتنفيذ التعريب في تطبيق Next.js الخاص بك، سنبدأ أولاً باختيار مكتبة i18n. هناك عدة مكتبات شهيرة، بما في ذلك next-intl. في هذا المثال، مع ذلك، سنستخدم TacoTranslate.

يقوم TacoTranslate بترجمة النصوص الخاصة بك أوتوماتيكياً إلى أي لغة باستخدام تقنيات الذكاء الاصطناعي المتقدمة، ويعفيك من الإدارة المملة لملفات JSON.

لِنثبتها باستخدام npm في الطرفية الخاصة بك:

npm install tacotranslate

الخطوة 2: إنشاء حساب مجاني على 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: "المجلد" الذي سيتم فيه تخزين السلاسل النصية الخاصة بك، مثل عنوان URL لموقعك الإلكتروني. اقرأ المزيد عن الأصول هنا.

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

الخطوة 3: إعداد 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

سوف نقوم تلقائيًا بتعريف TACOTRANSLATE_API_KEY و TACOTRANSLATE_PROJECT_LOCALE قريبًا.

إنشاء العميل في ملف منفصل يجعل من السهل إعادة استخدامه لاحقًا. getLocales هي مجرد دالة مساعدة تحتوي على بعض معالجة الأخطاء المدمجة. الآن، أنشئ ملفًا باسم /app/[locale]/tacotranslate.tsx, حيث سنقوم بتنفيذ موفر TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

لاحظ 'use client'; التي تشير إلى أن هذا مكون يعمل على جهة العميل.

مع وجود مزود السياق جاهز الآن، قم بإنشاء ملف باسم /app/[locale]/layout.tsx, وهو التخطيط الجذري في تطبيقنا. لاحظ أن هذا المسار يحتوي على مجلد يستخدم Dynamic Routes, حيث [locale] هو المعامل الديناميكي.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

أول شيء يجب ملاحظته هنا هو أننا نستخدم معامل Dynamic Route الخاص بنا [locale] لجلب الترجمات لتلك اللغة. بالإضافة إلى ذلك، فإن generateStaticParams يضمن أن جميع رموز اللغة (locale) التي قمت بتنشيطها لمشروعك مُعَدّة للعرض المسبق.

الآن، دعونا نبني أول صفحة لنا! أنشئ ملفًا باسم /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

لاحظ متغير revalidate الذي يخبر Next.js بإعادة بناء الصفحة بعد 60 ثانية، والحفاظ على تحديث ترجماتك.

الخطوة 4: تنفيذ العرض من جانب الخادم

تدعم TacoTranslate العرض من جانب الخادم. هذا يحسن تجربة المستخدم بشكل كبير عن طريق عرض المحتوى المترجم على الفور، بدلاً من ظهور لمحة من المحتوى غير المترجم أولاً. بالإضافة إلى ذلك، يمكننا تخطي طلبات الشبكة على العميل، لأننا نمتلك بالفعل الترجمات التي نحتاجها للصفحة التي يشاهدها المستخدم.

لإعداد التصيير من جانب الخادم، قم بإنشاء أو تعديل /next.config.js:

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

قم بتعديل فحص isProduction ليناسب إعدادك. إذا كانت true، سيعرض TacoTranslate مفتاح API العام. إذا كنا في بيئة محلية أو اختبارية أو بيئة تجهيز (isProduction is false)، سنستخدم مفتاح API السري read/write لضمان إرسال السلاسل الجديدة للترجمة.

لضمان عمل التوجيه وإعادة التوجيه كما هو متوقع، سنحتاج إلى إنشاء ملف باسم /middleware.ts. باستخدام Middleware, يمكننا توجيه المستخدمين إلى الصفحات المعروضة بلغتهم المفضلة.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

تأكد من إعداد matcher وفقًا لـ وثائق وسطية Next.js.

على العميل، يمكنك تعديل كوكي locale لتغيير اللغة المفضلة للمستخدم. يرجى الاطلاع على الكود الكامل للمثال للحصول على أفكار حول كيفية القيام بذلك!

الخطوة 5: النشر والاختبار!

لقد انتهينا! سيتم الآن ترجمة تطبيق React الخاص بك تلقائيًا عندما تضيف أي نصوص إلى مكون Translate. لاحظ أن البيئات التي تمتلك أذونات read/write على مفتاح API فقط هي التي ستكون قادرة على إنشاء نصوص جديدة لترجمتها. نوصي بوجود بيئة تحضيرية مغلقة ومؤمنة حيث يمكنك اختبار تطبيق الإنتاج الخاص بك باستخدام مفتاح API من هذا النوع، مضيفًا نصوصًا جديدة قبل الإطلاق المباشر. سيساعد هذا على منع أي شخص من سرقة مفتاح API السري الخاص بك، ومنع زيادة حجم مشروع الترجمة الخاص بك بإضافة نصوص جديدة غير مرتبطة.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the Pages Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!