ترجمة موقعك الإلكتروني باستخدام Vite و Svelte عبر Intlayer

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

لماذا تختار Intlayer مقارنة بالبدائل الأخرى؟

بالمقارنة مع الحلول الرئيسية مثل svelte-i18n أو i18next، يعد Intlayer حلاً يأتي مزودًا بتحسينات متكاملة مثل:

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

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

1. 1

   تثبيت التبعيات

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer init --interactive
   

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install intlayer svelte-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

   • svelte-intlayer الحزمة التي تدمج Intlayer مع تطبيق Svelte. توفر مزودي السياق hooks للتدويل في Svelte.

   • vite-intlayer يتضمن إضافة Vite لدمج Intlayer مع مجمّع Vite، بالإضافة إلى وسيط للكشف عن اللغة المفضلة للمستخدم، وإدارة الكوكيز، والتعامل مع إعادة توجيه URL.

2. 2

   تكوين مشروعك

   البنية

   في هذه البنية، يوفر svelte-intlayer مخازن تفاعلية وأدوات مساعدة لإدارة الترجمات داخل مكونات Svelte. توجد إعلانات المحتوى في src/ بجانب المكونات.

   bash

   نسخ المحتوى

   نسخ الكود

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

   .
   ├── src
   │   ├── app.content.ts
   │   ├── app.css
   │   ├── App.svelte                    # Root component
   │   ├── lib
   │   │   ├── Counter.svelte
   │   │   └── LocaleSwitcher.svelte
   │   ├── main.ts                       # Entry point
   │   └── vite-env.d.ts
   ├── index.html
   ├── intlayer.config.ts
   ├── package.json
   ├── svelte.config.js
   ├── tsconfig.json
   └── vite.config.ts
   

   التكوين

   أنشئ ملف تكوين لتحديد لغات تطبيقك:

   intlayer.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Your other locales
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

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

   توثيق التكوين
3. 3

   دمج Intlayer في تكوين Vite الخاص بك

   أضف مكون intlayer الإضافي إلى تكوينك.

   vite.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import { defineConfig } from "vite";
   import { svelte } from "@sveltejs/vite-plugin-svelte";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [svelte(), intlayer()],
   });
   

   يُستخدم مكون Vite الإضافي intlayer() لدمج Intlayer مع Vite. يضمن بناء ملفات إعلان المحتوى ويراقبها في وضع التطوير. كما يعرّف متغيرات بيئة Intlayer داخل تطبيق Vite. بالإضافة إلى ذلك، يوفر ألقابًا لتحسين الأداء.

4. 4

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

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

   src/app.content.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

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

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

   توثيق إعلان المحتوى
5. 5

   استخدام Intlayer في الكود الخاص بك

   src/App.svelte

   نسخ المحتوى

   نسخ الكود

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

   <script>
     import { useIntlayer } from "svelte-intlayer";
   
     const content = useIntlayer("app");
   </script>
   
   <div>
   
   
   <!-- عرض المحتوى كمحتوى بسيط -->
   <h1>{$content.title}</h1>
   <!-- لعرض المحتوى قابل للتحرير باستخدام المحرر -->
   <h1>{@const Title = $content.title}<Title /></h1>
   <!-- لعرض المحتوى كسلسلة نصية -->
   <div aria-label={$content.title.value}></div>
   <div aria-label={$content.title.toString()}></div>
   <div aria-label={String($content.title)}></div>
   

   إذا كان تطبيقك موجودًا بالفعل، يمكنك استخدام مترجم Intlayer، بالإضافة إلى أمر الاستخراج، لتحويل آلاف المكونات في ثانية واحدة.

   مترجم Intlayer

   أمر الاستخراج
6. 6

   تغيير لغة المحتوى الخاص بك

   اختياري

   src/App.svelte

   نسخ المحتوى

   نسخ الكود

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

   <script lang="ts">
   import  { getLocaleName } from 'intlayer';
   import { useLocale } from "svelte-intlayer";
   
   // الحصول على معلومات اللغة ودالة setLocale
   const { locale, availableLocales, setLocale } = useLocale();
   
   // التعامل مع تغيير اللغة
   const changeLocale = (event: Event) => {
     const target = event.target as HTMLSelectElement;
     const newLocale = target.value;
     setLocale(newLocale);
   };
   </script>
   
   <div>
     <select value={$locale} on:change={changeLocale}>
       {#each availableLocales ?? [] as loc}
         <option value={loc}>
           {getLocaleName(loc)}
         </option>
       {/each}
     </select>
   </div>
   

7. 7

   عرض Markdown

   اختياري

   يدعم Intlayer عرض محتوى Markdown مباشرة في تطبيق Svelte الخاص بك. بشكل افتراضي، يتم التعامل مع Markdown كنص عادي. لتحويل Markdown إلى HTML غني، يمكنك دمج @humanspeak/svelte-markdown، أو أي محلل Markdown آخر.

   لرؤية كيفية إعلان محتوى markdown باستخدام حزمة intlayer، راجع وثيقة markdown.

   src/App.svelte

   نسخ المحتوى

   نسخ الكود

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

   <script>
     import { setIntlayerMarkdown } from "svelte-intlayer";
   
     setIntlayerMarkdown((markdown) =>
      // عرض محتوى الماركداون كسلسلة نصية
      return markdown;
     );
   </script>
   
   <h1>{$content.markdownContent}</h1>
   

   يمكنك أيضًا الوصول إلى بيانات الـ front-matter الخاصة بالماركداون باستخدام الخاصية content.markdownContent.metadata.xxx.

8. 8

   إعداد محرر intlayer / نظام إدارة المحتوى

   اختياري

   لإعداد محرر intlayer، يجب عليك اتباع توثيق محرر intlayer.

   توثيق محرر intlayer

   لإعداد نظام إدارة المحتوى (CMS) الخاص بـ intlayer، يجب عليك اتباع توثيق نظام إدارة المحتوى intlayer.

   توثيق نظام إدارة المحتوى intlayer
9. 7

   إضافة التوجيه المحلي (localized Routing) لتطبيقك

   اختياري

   للتعامل مع التوجيه المحلي في تطبيق Svelte الخاص بك، يمكنك استخدام svelte-spa-router مع localeFlatMap من Intlayer لتوليد المسارات لكل لغة.

   أولاً، قم بتثبيت svelte-spa-router:

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install svelte-spa-router
   npx intlayer init
   

   ثم، أنشئ ملف Router.svelte لتعريف المسارات الخاصة بك:

   src/Router.svelte

   نسخ المحتوى

   نسخ الكود

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

   <script lang="ts">
   import { localeFlatMap } from "intlayer";
   import Router from "svelte-spa-router";
   import { wrap } from "svelte-spa-router/wrap";
   import App from "./App.svelte";
   
   const routes = Object.fromEntries(
       localeFlatMap(({locale, urlPrefix}) => [
       [
           urlPrefix || '/',
           wrap({
               component: App,
               props: {
                   locale,
               },
           }),
       ],
       ])
   );
   </script>
   
   <Router {routes} />
   

   قم بتحديث ملف main.ts لتركيب مكون Router بدلاً من App:

   src/main.ts

   نسخ المحتوى

   نسخ الكود

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

   import { mount } from "svelte";
   import Router from "./Router.svelte";
   
   const app = mount(Router, {
     target: document.getElementById("app")!,
   });
   
   export default app;
   

   أخيرًا، قم بتحديث ملف App.svelte الخاص بك لاستقبال الخاصية locale واستخدامها مع useIntlayer:

   src/App.svelte

   نسخ المحتوى

   نسخ الكود

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

   <script lang="ts">
   import type { Locale } from 'intlayer';
   import { useIntlayer } from "svelte-intlayer";
   import Counter from './lib/Counter.svelte';
   import LocaleSwitcher from './lib/LocaleSwitcher.svelte';
   
   export let locale: Locale;
   
   $: content = useIntlayer('app', locale);
   </script>
   
   <main>
     <div class="locale-switcher-container">
       <LocaleSwitcher currentLocale={locale} />
     </div>
   
     <!-- ... بقية تطبيقك ... -->
   </main>
   

   تكوين التوجيه على جانب الخادم (اختياري)

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

   ملاحظة: لاستخدام intlayerProxy في بيئة الإنتاج، تحتاج إلى نقل حزمة vite-intlayer من devDependencies إلى dependencies.

   منذ Intlayer v9، يتم توضيب intlayerProxy() مباشرة في plugin intlayer() وتفعيله بشكل افتراضي من خلال خيار routing.enableProxy (true افتراضياً). تسجيله بشكل منفصل كما هو موضح أدناه أصبح اختيارياً الآن، يتم الاحتفاظ به لأغراض التوافقية العكسية وللإعدادات التي تحتاج إلى التحكم في ترتيب plugins. اضبط routing.enableProxy: false للعزوف عن ذلك. انظر إلى ملاحظات الإصدار v9.

   ملاحظات الإصدار v9

   vite.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import { defineConfig } from "vite";
   import { svelte } from "@sveltejs/vite-plugin-svelte";
   import { intlayer } from "vite-intlayer";
   
   typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"
   import { defineConfig } from "vite";
   import { svelte } from "@sveltejs/vite-plugin-svelte";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [intlayerProxy(), // should be placed first
    svelte(), intlayer()],
   });
   

10. 8

    تغيير عنوان URL عند تغيير اللغة

    اختياري

    للسماح للمستخدمين بتغيير اللغة وتحديث عنوان URL وفقًا لذلك، يمكنك إنشاء مكون LocaleSwitcher. سيستخدم هذا المكون getLocalizedUrl من intlayer و push من svelte-spa-router.

    src/lib/LocaleSwitcher.svelte

    نسخ المحتوى

    نسخ الكود

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

    <script lang="ts">
    import { getLocaleName, getLocalizedUrl } from "intlayer";
    import { useLocale } from "svelte-intlayer";
    import { push } from "svelte-spa-router";
    
    export let currentLocale: string | undefined = undefined;
    
    // الحصول على معلومات اللغة
    const { locale, availableLocales } = useLocale();
    
    // التعامل مع تغيير اللغة
    const changeLocale = (event: Event) => {
      const target = event.target as HTMLSelectElement;
      const newLocale = target.value;
      const currentUrl = window.location.pathname;
      const url = getLocalizedUrl( currentUrl, newLocale);
      push(url);
    };
    </script>
    
    <div class="locale-switcher">
      <select value={currentLocale ?? $locale} onchange={changeLocale}>
        {#each availableLocales ?? [] as loc}
          <option value={loc}>
            {getLocaleName(loc)}
          </option>
        {/each}
      </select>
    </div>
    

11. 9

    الروابط المترجمة

    اختياري

    لأغراض SEO، من المستحسن إضافة بادئة locale إلى مساراتك (على سبيل المثال، /about, /fr/about).

    src/lib/components/Link.svelte

    نسخ المحتوى

    نسخ الكود

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

    <script lang="ts">
      import { getLocalizedUrl } from "intlayer";
      import { useLocale } from "svelte-intlayer";
    
      export let href = "";
      const { locale } = useLocale();
    
      // مساعد لإضافة البادئة إلى عنوان URL
      $: localizedHref = getLocalizedUrl(href, $locale);
    </script>
    
    <a href={localizedHref}>
      <slot />
    </a>
    

12. 1

    استخراج محتوى مكوناتك

    اختياري

    إذا كان لديك قاعدة بيانات كود موجودة، فقد يكون تحويل آلاف الملفات مستهلكًا للوقت.

    لتسهيل هذه العملية، يقترح Intlayer مترجمًا / مستخرجًا لتحويل مكوناتك واستخراج المحتوى.

    مترجمًا

    مستخرجًا

    لإعداده، يمكنك إضافة قسم compiler في ملف intlayer.config.ts الخاص بك:

    intlayer.config.ts

    نسخ المحتوى

    نسخ الكود

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

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... بقية التكوين الخاص بك
      compiler: {
        /**
         * يشير إلى ما إذا كان يجب تمكين المترجم.
         */
        enabled: true,
    
        /**
         * يحدد مسار ملفات المخرجات
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * يشير إلى ما إذا كان يجب حفظ المكونات بعد تحويلها. بهذه الطريقة، يمكن تشغيل المترجم مرة واحدة فقط لتحويل التطبيق، ثم يمكن إزالته.
         */
        saveComponents: false,
    
        /**
         * بادئة مفتاح القاموس
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    أمر الاستخراجمترجم Babel

    قم بتشغيل المستخرج لتحويل مكوناتك واستخراج المحتوى

    bash

    نسخ المحتوى

    نسخ الكود

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

    npx intlayer extract
    

    intlayer >= 9intlayer < 9

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    قم بتحديث vite.config.ts الخاص بك لتضمين ملحق intlayerCompiler:

    vite.config.ts

    نسخ المحتوى

    نسخ الكود

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

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    قم ببناء تطبيقك لتحويل مكوناتك واستخراج المحتوى

    bash

    نسخ المحتوى

    نسخ الكود

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

    npm run build # أو npm run dev
    

(اختياري) خريطة الموقع و robots.txt (توليد وقت البناء)

يوفّر Intlayer الدالتين generateSitemap وgetMultilingualUrls لتنسيق مخرجات جاهزة للزحّافات (sitemap.xml متعدد اللغات وrobots.txt) وكتابتها تلقائياً إلى public/. عادةً تشغّل سكربت Node صغير قبل Vite (مثلاً خطافات npm predev / prebuild).

خريطة الموقع

يولّد مولّد خرائط المواقع إعدادات اللغات ويضيف البيانات الوصفية المناسبة.

تدعم الخريطة مساحة الاسم xhtml:link (hreflang). بدلاً من قائمة عناوين مسطحة، يربط Intlayer بين جميع النسخ اللغوية لكل صفحة في الاتجاهين (مثل /about و/fr/about أو /about?lang=fr وفقًا لوضع التوجيه).

Robots.txt

استخدم getMultilingualUrls لتشمل قواعد Disallow كل المتغيرات المحلية للمسارات الحساسة.

1. أضف generate-seo.mjs في جذر المشروع

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, {
  siteUrl: "https://example.com",
});
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: https://example.com/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);

console.log("SEO files generated successfully.");

يجب تثبيت حزمة intlayer. عيّن SITE_URL في بيئة الإنتاج (مثلاً في CI).

يُفضّل generate-seo.mjs لـ ESM في Node. إن استخدمت generate-seo.js ففعّل "type": "module" في package.json أو ESM بطريقة أخرى.

2. شغّل السكربت قبل Vite

{
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

عدّل الأوامر إن كنت تستخدم pnpm أو yarn. يمكن استدعاء السكربت من CI أيضاً.

تكوين Git

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

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

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

إضافة VS Code

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

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

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

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

التعمق أكثر

للمضي قدمًا، يمكنك تنفيذ المحرر المرئي أو إخراج محتواك باستخدام نظام إدارة المحتوى (CMS).

الأسئلة الشائعة