ترجم موقع Angular 21 (Vite) الخاص بك باستخدام Intlayer | التدويل (i18n)

جدول المحتويات

ما هو Intlayer؟

Intlayer هي مكتبة تدويل (i18n) مفتوحة المصدر ومبتكرة مصممة لتبسيط دعم تعدد اللغات في تطبيقات الويب الحديثة.

باستخدام Intlayer، يمكنك:

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

دليل خطوة بخطوة لإعداد Intlayer في تطبيق Angular

راجع قالب التطبيق على GitHub.

الخطوة 1: تثبيت التبعيات

قم بتثبيت الحزم اللازمة باستخدام npm:

npm install intlayer angular-intlayernpm install @angular-builders/custom-esbuild --save-devnpx intlayer init

• intlayer

  الحزمة الأساسية التي توفر أدوات التدويل لإدارة التكوين، والترجمة، وتصريح المحتوى، والترجمة البرمجية، وأوامر CLI.

• angular-intlayer الحزمة التي تدمج Intlayer مع تطبيق Angular. توفر مزودي السياق والخطافات للتدويل في Angular.

• @angular-builders/custom-esbuild مطلوبة لتخصيص تكوين esbuild الخاص بـ Angular CLI.

الخطوة 2: تكوين مشروعك

قم بإنشاء ملف تكوين لتكوين لغات تطبيقك:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // اللغات الأخرى الخاصة بك
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

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

الخطوة 3: دمج Intlayer في تكوين Angular الخاص بك

لدمج Intlayer مع Angular CLI، تحتاج إلى استخدام باني مخصص (custom builder). يفترض هذا الدليل أنك تستخدم Vite/esbuild (الافتراضي لمشاريع Angular 21).

أولاً، قم بتعديل angular.json الخاص بك لاستخدام باني esbuild المخصص. قم بتحديث تكوينات build و serve:

{  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application", // replace "@angular/build:application"          "options": {            "define": {              "process.env": "{}",            },            "plugins": ["./esbuild.plugins.ts"],            "browser": "src/main.ts",            // ...          },        },        "serve": {          "builder": "@angular-builders/custom-esbuild:dev-server", // replace "@angular/build:dev-server"          "options": {            "prebundle": {              "exclude": [                "intlayer",                "angular-intlayer",                "@intlayer/config/built",                "@intlayer/core"              ]          },        },      },    },  },}

تأكد من استبدال your-app-name بالاسم الفعلي لمشروعك في angular.json.

بعد ذلك، قم بإنشاء ملف esbuild.plugins.ts في جذر مشروعك:

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

تقوم وظيفة intlayerEsbuildPlugin بتكوين esbuild مع Intlayer. حيث تقوم بإدخال الإضافة (plugin) للتعامل مع ملفات تصريح المحتوى وتعد إعدادات الأداء الأمثل.

مستخدمو NX: تقوم أدوات بناء Angular الخاصة بـ NX بتحميل ملفات المكونات الإضافية عبر دقة ESM الأصلية لـ Node ولا تقوم بترجمة ملفات المكونات الإضافية TypeScript تلقائيًا. استخدم ملف .mjs بدلاً من ذلك وقم بتحديث مرجع plugins في angular.json وفقًا لذلك:

esbuild.plugins.mjs

نسخ المحتوى

نسخ الكود

نسخ الكود إلى الحافظة

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

ثم في angular.json قم بالإشارة إلى "./esbuild.plugins.mjs" بدلاً من "./esbuild.plugins.ts".

الخطوة 4: صرح عن محتواك

أنشئ وأدِر تصريحات محتواك لتخزين الترجمات:

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

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

الخطوة 5: استخدم Intlayer في كودك

لاستخدام ميزات التدويل الخاصة بـ Intlayer في جميع أنحاء تطبيق Angular الخاص بك، يجب عليك توفير Intlayer في تكوين التطبيق.

import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { provideIntlayer } from "angular-intlayer";import { routes } from "./app.routes";export const appConfig: ApplicationConfig = {  providers: [    provideRouter(routes),    provideIntlayer(), // أضف مزود Intlayer هنا  ],};

بعد ذلك، يمكنك استخدام وظيفة useIntlayer داخل أي مكون.

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

وفي القالب الخاص بك:

<div class="content">  <h1>{{ content().title }}</h1>  <p>{{ content().congratulations }}</p></div>

يتم إرجاع محتوى Intlayer كـ Signal، لذا يمكنك الوصول إلى القيم باستدعاء الإشارة: content().title.

(اختياري) الخطوة 6: تغيير لغة محتواك

لتغيير لغة محتواك، يمكنك استخدام وظيفة setLocale التي توفرها وظيفة useLocale. يتيح لك هذا تعيين لغة التطبيق وتحديث المحتوى وفقًا لذلك.

قم بإنشاء مكون للتبديل بين اللغات:

import { Component } from "@angular/core";import { CommonModule } from "@angular/common";import { useLocale } from "angular-intlayer";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule],  template: `    <div class="locale-switcher">      <select        [value]="locale()"        (change)="setLocale($any($event.target).value)"      >        @for (loc of availableLocales; track loc) {          <option [value]="loc">{{ loc }}</option>        }      </select>    </div>  `,})export class LocaleSwitcherComponent {  localeCtx = useLocale();  locale = this.localeCtx.locale;  availableLocales = this.localeCtx.availableLocales;  setLocale = this.localeCtx.setLocale;}

ثم، استخدم هذا المكون في app.component.ts الخاص بك:

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "./locale-switcher.component";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet, LocaleSwitcherComponent],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

تكوين TypeScript

يستخدم Intlayer تعزيز الوحدة (Module Augmentation) للحصول على فوائد TypeScript وجعل قاعدة كودك أكثر قوة.

تأكد من أن تكوين TypeScript الخاص بك يتضمن الأنواع المُنشأة تلقائيًا.

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

تكوين Git

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

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

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

إضافة VS Code

لتحسين تجربة تطويرك مع Intlayer، يمكنك تثبيت إضافة Intlayer VS Code Extension الرسمية.

تثبيت من VS Code Marketplace

توفر هذه الإضافة:

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

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

اذهب أبعد من ذلك

للذهاب إلى أبعد من ذلك، يمكنك تنفيذ المحرر المرئي أو الاستعانة بمصادر خارجية لمحتواك باستخدام CMS.