أفضل حل للتدويل (i18n) في تطبيقات Next.js

كيف يعمل

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

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

هذا الدليل مخصص لتطبيقات Next.js التي تستخدم Pages Router.
إذا كنت تستخدم App 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

تأكد من عدم تسريب مفتاح واجهة برمجة التطبيقات السري 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_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, فيُرجى توسيع التعريف بالخصائص والكود الوارد أعلاه.

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

تتيح 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 مضبوط على 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!"/>
}

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

انتهينا! سيتم الآن ترجمة تطبيق Next.js الخاص بك تلقائيًا عندما تضيف أي سلاسل نصية إلى 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 App 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!