كيفية تنفيذ التدويل في تطبيق Next.js الذي يستخدم Pages Router
اجعل تطبيق React الخاص بك أكثر سهولة في الوصول ووسع نطاق وصولك إلى أسواق جديدة باستخدام التعريب (i18n).
مع ازدياد العولمة في العالم، يصبح من المهم بشكل متزايد لمطوري الويب بناء تطبيقات تلبي احتياجات المستخدمين من مختلف البلدان والثقافات. واحدة من الطرق الرئيسية لتحقيق ذلك هو من خلال التدويل (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
تأكد من عدم تسريب مفتاح 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_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: انشر واختبر!
لقد انتهينا! سيتم الآن ترجمة تطبيق React الخاص بك تلقائيًا عندما تضيف أي سلاسل إلى مكوّن Translate
. لاحظ أن البيئات التي تمتلك أذونات read/write
على مفتاح API فقط ستكون قادرة على إنشاء سلاسل جديدة لترجمتها. نوصي بوجود بيئة تحضير مغلقة ومؤمّنة حيث يمكنك اختبار تطبيق الإنتاج الخاص بك باستخدام مفتاح API من هذا النوع، وإضافة سلاسل جديدة قبل الإطلاق. سيمنع هذا أي شخص أي شخص من سرقة مفتاح الـ API السري الخاص بك، وقد يؤدي أيضًا إلى تضخيم مشروع الترجمة الخاص بك بإضافة سلاسل جديدة وغير ذات صلة.
تأكد من الاطلاع على المثال الكامل في ملفنا على GitHub. هناك، ستجد أيضًا مثالًا يوضح كيفية القيام بذلك باستخدام App Router! إذا واجهت أي مشاكل، فلا تتردد في التواصل معنا، ويسعدنا جدًا مساعدتك.
تتيح لك TacoTranslate تعريب تطبيقات React الخاصة بك تلقائيًا وبسرعة إلى ومن أكثر من 75 لغة. ابدأ اليوم!