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

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

ما هو Intlayer؟

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

مع Intlayer، يمكنك:

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

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

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

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

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

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

• intlayer

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

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

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

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

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

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: دمج Intlayer في تكوين Vite الخاص بك

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

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: إعلان المحتوى الخاص بك

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

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,mjx,cjs,cjx}).

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

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

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

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

<script lang="ts">import  { getLocaleName } from 'intlayer';import { useLocale } from 'svelte-intlayer';// الحصول على معلومات اللغة ودالة setLocaleconst { 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: عرض Markdown

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

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

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

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

(اختياري) الخطوة 8: إعداد محرر intlayer / نظام إدارة المحتوى (CMS)

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

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

بالتوازي، في تطبيق Svelte الخاص بك، يجب عليك إضافة السطر التالي في تخطيط (layout)، أو في جذر التطبيق:

import { useIntlayerEditor } from "svelte-intlayer";useIntlayerEditor();

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

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

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

npm install svelte-spa-router

ثم، أنشئ ملف 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 as any,            props: {                locale,            },        }),    ],    ]));</script><Router {routes} />

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

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

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

<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.

import { defineConfig } from "vite";import { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer, intlayerProxy } 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, intlayerProxy } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [svelte(), intlayer(), intlayerProxy()],});

(اختياري) الخطوة 8: تغيير عنوان URL عند تغيير اللغة

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

<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>

تكوين Git

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

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

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

إضافة VS Code

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

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

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

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

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

التعمق أكثر

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