ترجم Nest backend باستخدام Intlayer | التدويل (i18n)

express-intlayer هو وسيط قوي للتدويل (i18n) لتطبيقات Express، مصمم لجعل خدمات الخلفية الخاصة بك متاحة عالميًا من خلال تقديم استجابات محلية بناءً على تفضيلات العميل. نظرًا لأن NestJS مبني على Express، يمكنك دمج express-intlayer بسلاسة في تطبيقات NestJS الخاصة بك للتعامل مع المحتوى متعدد اللغات بفعالية.

حالات الاستخدام العملية

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

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

• إرسال رسائل بريد إلكترونية متعددة اللغات: سواء كانت رسائل بريد إلكترونية معاملات أو حملات تسويقية أو إشعارات، يمكن لإرسال رسائل البريد الإلكترونية بلغة المستقبل أن يزيد بشكل كبير من التفاعل والفعالية.

• إشعارات Push متعددة اللغات: بالنسبة للتطبيقات المحمولة، يمكن لإرسال إشعارات push بلغة المستخدم المفضلة أن يحسّن التفاعل والاحتفاظ بالمستخدمين. يمكن لهذا اللمس الشخصي أن يجعل الإشعارات تبدو أكثر صلة واقعية وقابلية للتطبيق.

• اتصالات أخرى: أي شكل من أشكال الاتصال من الخادم الخلفي، مثل رسائل SMS والتنبيهات النظامية أو تحديثات واجهة المستخدم، تستفيد من كونها بلغة المستخدم، مما يضمن الوضوح ويحسن تجربة المستخدم الشاملة.

من خلال دولية Backend، لا تحترم تطبيقك الفروقات الثقافية فحسب، بل تتوافق بشكل أفضل مع احتياجات السوق العالمية، مما يجعلها خطوة أساسية في توسع نطاق خدماتك على مستوى العالم.

البدء

إنشاء مشروع NestJS جديد

npm install -g @nestjs/cli
nest new my-nest-app

التثبيت

لبدء استخدام express-intlayer، قم بتثبيت الحزمة باستخدام npm:

npx intlayer init --interactive

علامة --interactive اختيارية. استخدم intlayer-cli init إذا كنت وكيل ذكاء اصطناعي.

سيقوم هذا الأمر باكتشاف بيئتك وتثبيت الحزم المطلوبة. على سبيل المثال:

npm install intlayer express-intlayer

تكوين tsconfig.json

لاستخدام Intlayer مع TypeScript، تأكد من إعداد ملف tsconfig.json لدعم وحدات ES. يمكنك القيام بذلك عن طريق تعيين خيارات module و moduleResolution إلى nodenext.

{
  compilerOptions: {
    module: "nodenext",
    moduleResolution: "nodenext",
    // ... خيارات أخرى
  },
}

الإعداد

قم بتكوين إعدادات التدويل بإنشاء ملف intlayer.config.ts في جذر مشروعك:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

أعلن عن المحتوى الخاص بك

قم بإنشاء وإدارة إعلانات المحتوى الخاصة بك لتخزين الترجمات:

يمكن تعريف إعلانات المحتوى الخاصة بك في أي مكان في تطبيقك طالما تم تضمينها في دليل contentDir (افتراضياً، ./src). ويجب أن تطابق امتداد ملف إعلان المحتوى (افتراضياً، .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

لمزيد من التفاصيل، راجع توثيق إعلان المحتوى.

إعداد وسيط Express

قم بدمج وسيط express-intlayer في تطبيق NestJS الخاص بك للتعامل مع التدويل:

import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { intlayer } from "express-intlayer";

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(intlayer()).forRoutes("*"); // تطبيق على جميع المسارات
  }
}

استخدام الترجمات في خدماتك أو وحدات التحكم الخاصة بك

يمكنك الآن استخدام دالة getIntlayer للوصول إلى الترجمات في خدماتك أو وحدات التحكم الخاصة بك:

import { Injectable } from "@nestjs/common";
import { getIntlayer } from "express-intlayer";

@Injectable()
export class AppService {
  getHello(): string {
    return getIntlayer("app").greet;
  }
}

التوافق

express-intlayer متوافق تمامًا مع:

• react-intlayer لتطبيقات React
• next-intlayer لتطبيقات Next.js
• vite-intlayer لتطبيقات Vite

كما يعمل بسلاسة مع أي حل للتدويل عبر بيئات مختلفة، بما في ذلك المتصفحات وطلبات API. يمكنك تخصيص الوسيط لاكتشاف اللغة من خلال الرؤوس أو ملفات تعريف الارتباط:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... خيارات التكوين الأخرى
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

بشكل افتراضي، سيقوم express-intlayer بتفسير رأس Accept-Language لتحديد اللغة المفضلة للعميل.

لمزيد من المعلومات حول التكوين والمواضيع المتقدمة، قم بزيارة التوثيق.

تكوين TypeScript

يستفيد express-intlayer من القدرات القوية لـ TypeScript لتعزيز عملية التدويل. يضمن النوع الثابت في TypeScript أن يتم تضمين كل مفتاح ترجمة، مما يقلل من خطر فقدان الترجمات ويحسن من سهولة الصيانة.

تأكد من تضمين الأنواع التي تم إنشاؤها تلقائيًا (افتراضيًا في ./types/intlayer.d.ts) في ملف tsconfig.json الخاص بك.

{
  // ... تكوينات TypeScript الحالية الخاصة بك
  include: [
    // ... تكوينات TypeScript الحالية الخاصة بك
    ".intlayer/**/*.ts", // تضمين الأنواع التي تم إنشاؤها تلقائيًا
  ],
}

امتداد VS Code

لتحسين تجربة التطوير الخاصة بك مع Intlayer، يمكنك تثبيت امتداد Intlayer الرسمي لـ VS Code.

التثبيت من سوق VS Code

يوفر هذا الامتداد:

• الإكمال التلقائي لمفاتيح الترجمة.
• الكشف الفوري عن الأخطاء للترجمات المفقودة.
• معاينات داخلية للمحتوى المترجم.
• إجراءات سريعة لإنشاء وتحديث الترجمات بسهولة.

لمزيد من التفاصيل حول كيفية استخدام الامتداد، راجع توثيق امتداد Intlayer لـ VS Code.

إعداد Git

يوصى بتجاهل الملفات التي يتم إنشاؤها بواسطة Intlayer. هذا يسمح لك بتجنب إضافتها إلى مستودع Git الخاص بك.

لعمل ذلك، يمكنك إضافة التعليمات التالية إلى ملف .gitignore الخاص بك:

# تجاهل الملفات التي تم إنشاؤها بواسطة Intlayer
.intlayer