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

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

لماذا Intlayer على البدائل؟

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

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

انظر إلى Application Template على GitHub.

للبدء، أنشئ مشروع SvelteKit جديد. إليك الهيكل النهائي الذي سننشئه:

.
├── intlayer.config.ts
├── package.json
├── src
│   ├── app.d.ts
│   ├── app.html
│   ├── hooks.server.ts
│   ├── lib
│   │   ├── getLocale.ts
│   │   ├── LocaleSwitcher.svelte
│   │   └── LocalizedLink.svelte
│   ├── params
│   │   └── locale.ts
│   └── routes
│       ├── [[locale=locale]]
│       │   ├── +layout.svelte
│       │   ├── +layout.ts
│       │   ├── +page.svelte
│       │   ├── +page.ts
│       │   ├── about
│       │   │   ├── +page.svelte
│       │   │   ├── +page.ts
│       │   │   └── page.content.ts
│       │   ├── Counter.content.ts
│       │   ├── Counter.svelte
│       │   ├── Header.content.ts
│       │   ├── Header.svelte
│       │   ├── home.content.ts
│       │   └── layout.content.ts
│       ├── +layout.svelte
│       └── layout.css
├── static
│   ├── favicon.svg
│   └── robots.txt
├── svelte.config.js
├── tsconfig.json
└── vite.config.ts

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: الحزمة الأساسية للترجمة الدولية (i18n).
   • svelte-intlayer: يوفر موفري السياق والمخازن لـ Svelte/SvelteKit.
   • vite-intlayer: إضافة Vite لدمج إعلانات المحتوى مع عملية البناء.
2. 2

   تكوين مشروعك

   قم بإنشاء ملف تكوين في جذر مشروعك:

   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;
   

3. 3

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

   قم بتحديث ملف vite.config.ts الخاص بك ليشمل إضافة Intlayer. تتولى هذه الإضافة تحويل ملفات المحتوى الخاصة بك.

   vite.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import { sveltekit } from "@sveltejs/kit/vite";
   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [intlayer(), sveltekit()], // ترتيب الإضافات مهم، يجب وضع Intlayer قبل SvelteKit
   });
   

4. 4

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

   قم بإنشاء ملفات إعلان المحتوى في أي مكان داخل مجلد src الخاص بك (مثلًا، src/lib/content أو بجانب مكوناتك). تقوم هذه الملفات بتعريف المحتوى القابل للترجمة لتطبيقك باستخدام دالة t() لكل لغة.

5. 5

   استخدام Intlayer في مكوناتك

   الآن يمكنك استخدام دالة useIntlayer في أي مكون Svelte. تُرجع مخزنًا تفاعليًا يتم تحديثه تلقائيًا عند تغيير اللغة. ستحترم الدالة تلقائيًا اللغة الحالية (أثناء SSR والتنقل على جانب العميل).

   للوصول إلى قيمته التفاعلية (مثلًا، $content.title).

   src/lib/components/Component.svelte

   نسخ المحتوى

   نسخ الكود

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

   <script lang="ts">
     import { useIntlayer } from "svelte-intlayer";
   
     // "hero-section" تتوافق مع المفتاح المُعرف في الخطوة 4
     const content = useIntlayer("hero-section");
   </script>
   
   <!-- عرض المحتوى كمحتوى بسيط -->
   <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>
   

6. 6

   إعداد التوجيه

   اختياري

   توضح الخطوات التالية كيفية إعداد التوجيه بناءً على اللغة في SvelteKit. يتيح هذا لعناوين URL الخاصة بك أن تتضمن بادئة اللغة (مثل /en/about، /fr/about) لتحسين تحسين محركات البحث وتجربة المستخدم.

   bash

   نسخ المحتوى

   نسخ الكود

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

   .
   └─── src
       ├── app.d.ts                  # تعريف نوع اللغة
       ├── hooks.server.ts           # إدارة توجيه اللغة
       ├── lib
       │   └── getLocale.ts          # التحقق من اللغة من الهيدر أو الكوكيز
       ├── params
       │   └── locale.ts             # تعريف معامل اللغة
       └── routes
           ├── [[locale=locale]]     # تغليف في مجموعة مسارات لتعيين اللغة
           │   ├── +layout.svelte    # التخطيط المحلي للمسار
           │   ├── +layout.ts
           │   ├── +page.svelte
           │   ├── +page.ts
           │   └── about
           │       ├── +page.svelte
           │       └── +page.ts
           └── +layout.svelte         # التخطيط الجذري للخطوط والأنماط العامة
   

7. 7

   التعامل مع اكتشاف اللغة على جانب الخادم

   في SvelteKit، يحتاج الخادم إلى معرفة لغة المستخدم لعرض المحتوى الصحيح أثناء العرض من جانب الخادم (SSR). نستخدم hooks.server.ts لاكتشاف اللغة من عنوان URL أو ملفات تعريف الارتباط.

   قم بإنشاء أو تعديل الملف src/hooks.server.ts:

   src/hooks.server.ts

   نسخ المحتوى

   نسخ الكود

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

   import type { Handle } from "@sveltejs/kit";
   import { getLocalizedUrl } from "intlayer";
   import { getLocale } from "$lib/getLocale";
   
   export const handle: Handle = async ({ event, resolve }) => {
     const detectedLocale = getLocale(event);
   
     // تحقق مما إذا كان المسار الحالي يبدأ بالفعل بلغة (مثل /fr، /en)
     const pathname = event.url.pathname;
     const targetPathname = getLocalizedUrl(pathname, detectedLocale);
   
     // إذا لم تكن هناك لغة في عنوان URL (مثل زيارة المستخدم لـ "/")، قم بإعادة توجيههم
     if (targetPathname !== pathname) {
       return new Response(undefined, {
         headers: { Location: targetPathname },
         status: 307, // إعادة توجيه مؤقتة
       });
     }
   
     return resolve(event, {
       transformPageChunk: ({ html }) => html.replace("%lang%", detectedLocale),
     });
   };
   

   ثم، أنشئ مساعدًا للحصول على لغة المستخدم من حدث الطلب:

   src/lib/getLocale.ts

   نسخ المحتوى

   نسخ الكود

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

   import {
     configuration,
     getLocaleFromStorage,
     localeDetector,
     type Locale,
   } from "intlayer";
   import type { RequestEvent } from "@sveltejs/kit";
   
   /**
    * الحصول على لغة المستخدم من حدث الطلب.
    * تُستخدم هذه الدالة في الخطاف `handle` في الملف `src/hooks.server.ts`.
    *
    * تحاول أولاً الحصول على اللغة من تخزين Intlayer (الكوكيز أو رؤوس مخصصة).
    * إذا لم يتم العثور على اللغة، تعود إلى تفاوض "Accept-Language" الخاص بالمتصفح.
    *
    * @param event - حدث الطلب من SvelteKit
    * @returns لغة المستخدم
    */
   export const getLocale = (event: RequestEvent): Locale => {
     const defaultLocale = configuration?.internationalization?.defaultLocale;
   
     // محاولة الحصول على اللغة من تخزين Intlayer (الكوكيز أو الرؤوس)
     const storedLocale = getLocaleFromStorage({
       // الوصول إلى ملفات تعريف الارتباط في SvelteKit
       getCookie: (name: string) => event.cookies.get(name) ?? null,
       // الوصول إلى رؤوس الطلب في SvelteKit
       getHeader: (name: string) => event.request.headers.get(name) ?? null,
     });
   
     if (storedLocale) {
       return storedLocale;
     }
   
     // الرجوع إلى تفاوض "Accept-Language" في المتصفح
     const negotiatorHeaders: Record<string, string> = {};
   
     // تحويل كائن رؤوس SvelteKit إلى سجل بسيط Record<string, string>
     event.request.headers.forEach((value, key) => {
       negotiatorHeaders[key] = value;
     });
   
     // التحقق من اللغة من رأس `Accept-Language`
     const userFallbackLocale = localeDetector(negotiatorHeaders);
   
     if (userFallbackLocale) {
       return userFallbackLocale;
     }
   
     // إرجاع اللغة الافتراضية إذا لم يتم العثور على تطابق
     return defaultLocale;
   };
   

   getLocaleFromStorage سيتحقق من اللغة من الهيدر أو الكوكي حسب تكوينك. راجع Configuration لمزيد من التفاصيل.

   دالة localeDetector ستتعامل مع هيدر Accept-Language وتعيد أفضل تطابق.

   إذا لم يتم تكوين اللغة، نريد إرجاع خطأ 404. لجعل الأمر أسهل، يمكننا إنشاء دالة match للتحقق مما إذا كانت اللغة صالحة:

   /src/params/locale.ts

   نسخ المحتوى

   نسخ الكود

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

   export const match = (param: Locale = defaultLocale): boolean =>
     locales.includes(param);
   

   ملاحظة: تأكد من أن ملف src/app.d.ts الخاص بك يتضمن تعريف اللغة:

   typescript

   نسخ المحتوى

   نسخ الكود

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

   declare global {
     namespace App {
       interface Locals {
         locale: import("intlayer").Locale;
       }
     }
   }
   

   بالنسبة لملف +layout.svelte، يمكننا إزالة كل شيء، للاحتفاظ فقط بالمحتوى الثابت، غير المرتبط بالتدويل (i18n):

   src/+layout.svelte

   نسخ المحتوى

   نسخ الكود

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

   <script lang="ts">
        import './layout.css';
   
       let { children } = $props();
   </script>
   
   <div class="app">
       {@render children()}
   </div>
   
   <style>
       .app {
       /*  */
       }
   </style>
   

   ثم، أنشئ صفحة وتخطيط جديد تحت مجموعة [[locale=locale]]:

   src/routes/[[locale=locale]]/+layout.ts

   نسخ المحتوى

   نسخ الكود

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

   import type { Load } from "@sveltejs/kit";
   import { defaultLocale, type Locale } from "intlayer";
   
   export const prerender = true;
   
   // استخدم النوع العام Load
   export const load: Load = ({ params }) => {
     const locale: Locale = (params.locale as Locale) ?? defaultLocale;
   
     return {
       locale,
     };
   };
   

   src/routes/[[locale=locale]]/+layout.svelte

   نسخ المحتوى

   نسخ الكود

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

   <script lang="ts">
       import type { Snippet } from 'svelte';
       import { useIntlayer, setupIntlayer } from "svelte-intlayer";
       import Header from './Header.svelte';
       import type { LayoutData } from './$types';
   
       let { children, data }: { children: Snippet, data: LayoutData } = $props();
   
       // تهيئة Intlayer باستخدام اللغة من المسار
     $effect(() => {
         setupIntlayer(data.locale);
     });
       // استخدام قاموس محتوى التخطيط
       const layoutContent = useIntlayer('layout');
   </script>
   
   <Header />
   
   <main>
       {@render children()}
   </main>
   
   <footer>
       <p>
           {$layoutContent.footer.prefix.value}{' '}
           <a href="https://svelte.dev/docs/kit">{$layoutContent.footer.linkLabel.value}</a>{' '}
           {$layoutContent.footer.suffix.value}
       </p>
   </footer>
   
   <style>
     /*  */
   </style>
   

   src/routes/[[locale=locale]]/+page.ts

   نسخ المحتوى

   نسخ الكود

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

   export const prerender = true;
   

   src/routes/[[locale=locale]]/+page.svelte

   نسخ المحتوى

   نسخ الكود

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

   <script lang="ts">
       import { useIntlayer } from "svelte-intlayer";
   
       // استخدم قاموس محتوى الصفحة الرئيسية
       const homeContent = useIntlayer('home');
   </script>
   
   <svelte:head>
       <title>{$homeContent.title.value}</title>
   </svelte:head>
   
   <section>
       <h1>
           {$homeContent.title}
       </h1>
   </section>
   
   <style>
     /*  */
   </style>
   

8. 8

   الروابط الدولية

   اختياري

   من أجل تحسين محركات البحث (SEO)، يُنصح بإضافة بادئة اللغة إلى مساراتك (على سبيل المثال، /en/about، /fr/about). يقوم هذا المكون تلقائيًا بإضافة بادئة اللغة الحالية لأي رابط.

   src/lib/components/LocalizedLink.svelte

   نسخ المحتوى

   نسخ الكود

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

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

   إذا كنت تستخدم goto من SvelteKit، يمكنك استخدام نفس المنطق مع getLocalizedUrl للتنقل إلى عنوان URL المحلي:

   typescript

   نسخ المحتوى

   نسخ الكود

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

   import { goto } from "$app/navigation";
   import { getLocalizedUrl } from "intlayer";
   import { useLocale } from "svelte-intlayer";
   
   const { locale } = useLocale();
   const localizedPath = getLocalizedUrl("/about", $locale);
   goto(localizedPath); // ينتقل إلى /en/about أو /fr/about حسب اللغة
   

9. 9

   مبدل اللغة

   اختياري

   للسماح للمستخدمين بتغيير اللغة، قم بتحديث عنوان URL.

   src/lib/components/LanguageSwitcher.svelte

   نسخ المحتوى

   نسخ الكود

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

   <script lang="ts">
     import { getLocalizedUrl, getLocaleName } from 'intlayer';
     import { useLocale } from "svelte-intlayer";
     import { page } from '$app/stores';
     import { goto } from '$app/navigation';
   
     const { locale, setLocale, availableLocales } = useLocale({
       onLocaleChange: (newLocale) => {
         const localizedPath = getLocalizedUrl($page.url.pathname, newLocale);
         goto(localizedPath);
       },
     });
   </script>
   
   <ul class="locale-list">
     {#each availableLocales as localeEl}
       <li>
         <a
           href={getLocalizedUrl($page.url.pathname, localeEl)}
           onclick={(e) => {
             e.preventDefault();
             setLocale(localeEl); // سيقوم بتعيين اللغة في المتجر وتفعيل onLocaleChange
           }}
           class:active={$locale === localeEl}
         >
           {getLocaleName(localeEl)}
         </a>
       </li>
     {/each}
   </ul>
   
   <style>
     /* */
   </style>
   

10. 10

    إضافة وكيل خلفي

    اختياري

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

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

    vite.config.ts

    نسخ المحتوى

    نسخ الكود

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

    import { defineConfig } from "vite";
    import { intlayer } from "vite-intlayer";
    import { sveltekit } from "@sveltejs/kit/vite";
    
    // https://vitejs.dev/config/
    export default defineConfig({
      plugins: [
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
        sveltekit(),
      ],],
    });
    

11. 11

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

    اختياري

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

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

    لكي تتمكن من عرض محدد محرر intlayer، سيتعين عليك استخدام بناء جملة المكون في محتوى intlayer الخاص بك.

    Component.svelte

    نسخ المحتوى

    نسخ الكود

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

    <script lang="ts">
      import { useIntlayer } from "svelte-intlayer";
    
      const content = useIntlayer("component");
    </script>
    
    <div>
    
      <!-- عرض المحتوى كمحتوى بسيط -->
      <h1>{$content.title}</h1>
    
      <!-- عرض المحتوى كمكون (مطلوب من قبل المحرر) -->
      {@const Component = $content.component}<Component />
    </div>
    

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

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

babel.config.js

نسخ المحتوى

نسخ الكود

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

const {
  intlayerExtractBabelPlugin,
  getExtractPluginOptions,
} = require("@intlayer/babel");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    // استخراج المحتوى من المكونات إلى القواميس
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
  ],
};

bash

نسخ المحتوى

نسخ الكود

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

npm run build # أو npm run dev

إعدادات Git

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

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

التعمق أكثر

• المحرر المرئي: دمج المحرر المرئي لـ Intlayer لتحرير الترجمات مباشرة من واجهة المستخدم.
• نظام إدارة المحتوى (CMS): قم بفصل إدارة المحتوى الخاصة بك باستخدام نظام إدارة المحتوى Intlayer.