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

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

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

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

دليل خطوة بخطوة لتهيئة Intlayer في Astro

تحقق من نموذج التطبيق على GitHub.

1. 1

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

   قم بتثبيت الحزم اللازمة باستخدام مدير الحزم المفضل لديك:

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer init --interactive
   

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install intlayer astro-intlayer
   

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install intlayer astro-intlayer
   # اختياري: إذا كنت ستضيف دعم React islands
   npm install react react-dom react-intlayer @astrojs/react
   

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

   • astro-intlayer تتضمن إضافة تكامل Astro لربط Intlayer بـ Vite bundler، بالإضافة إلى وسيط (middleware) لاكتشاف لغة المستخدم المفضلة، وإدارة ملفات تعريف الارتباط (cookies)، والتعامل مع إعادة توجيه الروابط.

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;
   

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

3. 3

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

   أضف إضافة intlayer إلى تكوين Astro الخاص بك.

   astro.config.ts

   نسخ المحتوى

   نسخ الكود

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

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [intlayer()],
   });
   

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

4. 4

   تعريف المحتوى الخاص بك

   أنشئ وأدِر تعريفات المحتوى لتخزين الترجمات:

   src/app.content.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { t, type Dictionary } from "intlayer";
   import type { ReactNode } from "react";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
         ar: "مرحبا بالعالم",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

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

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

5. 5

   استخدام المحتوى في Astro

   يمكنك استهلاك القواميس مباشرة في ملفات .astro الخاصة بك باستخدام المساعدين الأساسيين المصدرين من intlayer.

   src/pages/index.astro

   نسخ المحتوى

   نسخ الكود

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

   ---
   import {
     getIntlayer,
     getLocaleFromPath,
     getLocalizedUrl,
     defaultLocale,
     localeMap,
     getHTMLTextDir,
     type LocalesValues,
   } from "intlayer";
   import LocaleSwitcher from "../components/LocaleSwitcher.astro";
   
   // Get the current locale from the URL (e.g. /es/about -> 'es')
   const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
   
   // Get the content for the 'app' dictionary
   const { title } = getIntlayer("app", locale);
   ---
   
   <!doctype html>
   <html lang={locale} dir={getHTMLTextDir(locale)}>
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
       <title>{title}</title>
   
       <!-- Canonical link: Tells search engines which is the primary version of this page -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang: Tell Google about all localized versions -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <!-- x-default: Fallback for users in unmatched languages -->
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <header>
         <LocaleSwitcher />
       </header>
       <main>
         <h1>{title}</h1>
       </main>
     </body>
   </html>
   

6. 6

   التوجيه المترجم

   أنشئ أجزاء مسار ديناميكية لخدمة الصفحات المترجمة (مثل src/pages/[locale]/index.astro):

   src/pages/[locale]/index.astro

   نسخ المحتوى

   نسخ الكود

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

   ---
   import { getIntlayer } from "intlayer";
   
   const { title } = getIntlayer('app');
   ---
   
   <h1>{title}</h1>
   

   يضيف تكامل Astro وسيط Vite الذي يساعد في التوجيه الحساس للغة وتعريفات البيئة أثناء التطوير. يمكنك أيضًا إنشاء روابط عبر اللغات باستخدام منطقك الخاص أو أدوات intlayer مثل getLocalizedUrl.

7. 7

   إضافة مبدل اللغة

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

   src/components/LocaleSwitcher.astro

   نسخ المحتوى

   نسخ الكود

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

   ---
   import {
     locales,
     getLocaleName,
     getLocalizedUrl,
     getLocaleFromPath,
     getPathWithoutLocale,
     type LocalesValues,
   } from "intlayer";
   
   const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
   const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
   ---
   
   <nav>
     {
       locales.map((localeItem) => (
         <a
           href={getLocalizedUrl(pathWithoutLocale, localeItem)}
           data-locale={localeItem}
           aria-current={localeItem === locale ? "page" : undefined}
         >
           {getLocaleName(localeItem)}
         </a>
       ))
     }
   </nav>
   
   <script>
     import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";
   
     const localeLinks = document.querySelectorAll("[data-locale]");
   
     localeLinks.forEach((link) => {
       link.addEventListener("click", (e) => {
         const locale = link.getAttribute("data-locale") as LocalesValues;
   
         // Update the locale cookie
         setLocaleInStorageClient(locale);
       });
     });
   </script>
   
   <style>
     nav {
       display: flex;
       gap: 1rem;
     }
     a[aria-current="page"] {
       font-weight: bold;
       text-decoration: underline;
     }
   </style>
   

   ملاحظة حول الاستمرارية: يضمن استخدام setLocaleInStorageClient في السكريبت الخاص بالعميل حفظ تفضيل اللغة للمستخدم في ملف تعريف الارتباط (cookie). يتيح ذلك لبرمجية Intlayer الوسيطة تذكر الاختيار وتوجيه المستخدم تلقائيًا إلى لغته المفضلة في الزيارات المستقبلية.

8. 8

   خريطة الموقع وRobots.txt

   توفر Intlayer أدوات لإنشاء خريطة موقع مترجمة وملفات robots.txt ديناميكيًا.

   خريطة الموقع (Sitemap)

   Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.

   The Intlayer generated sitemap supports the xhtml:link namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., /about, /about?lang=fr, and /about?lang=es). This ensures search engines correctly index and serve the right language version to the right audience.

   أنشئ src/pages/sitemap.xml.ts لإنشاء خريطة موقع تتضمن جميع مساراتك المترجمة.

   src/pages/sitemap.xml.ts

   نسخ المحتوى

   نسخ الكود

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

   import type { APIRoute } from "astro";
   import { generateSitemap, type SitemapUrlEntry } from "intlayer";
   
   const pathList: SitemapUrlEntry[] = [
     { path: "/", changefreq: "daily", priority: 1.0 },
     { path: "/about", changefreq: "monthly", priority: 0.7 },
   ];
   
   const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
   
     return new Response(xmlOutput, {
       headers: { "Content-Type": "application/xml" },
     });
   };
   

   Robots.txt

   أنشئ src/pages/robots.txt.ts للتحكم في زحف محركات البحث.

   src/pages/robots.txt.ts

   نسخ المحتوى

   نسخ الكود

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

   import type { APIRoute } from "astro";
   import { getMultilingualUrls } from "intlayer";
   
   const getAllMultilingualUrls = (urls: string[]) =>
     urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
   
   const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
   
   export const GET: APIRoute = ({ site }) => {
     const robotsTxt = [
       "User-agent: *",
       "Allow: /",
       ...disallowedPaths.map((path) => `Disallow: ${path}`),
       "",
       `Sitemap: ${new URL("/sitemap.xml", site).href}`,
     ].join("\n");
   
     return new Response(robotsTxt, {
       headers: { "Content-Type": "text/plain" },
     });
   };
   

9. 9

   استمر في استخدام إطارات العمل المفضلة لديك

   استمر في بناء تطبيقك باستخدام إطار العمل الذي تختاره.

   • Intlayer + React: Intlayer مع React
   • Intlayer + Vue: Intlayer مع Vue
   • Intlayer + Svelte: Intlayer مع Svelte
   • Intlayer + Solid: Intlayer مع Solid
   • Intlayer + Preact: Intlayer مع Preact
10. 15

    Extract the content of your components

    اختياري

    If you have an existing codebase, transforming thousands of files can be time-consuming.

    To ease this process, Intlayer propose a compiler / extractor to transform your components and extract the content.

    To set it up, you can add a compiler section in your intlayer.config.ts file:

    intlayer.config.ts

    نسخ المحتوى

    نسخ الكود

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

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Rest of your config
      compiler: {
        /**
         * Indicates if the compiler should be enabled.
         */
        enabled: true,
    
        /**
         * Defines the output files path
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Indicates if the components should be saved after being transformed.
         *
         * - If `true`, the compiler will rewrite the component file in the disk. So the transformation will be permanent, and the compiler will skip the transformation for the next process. That way, the compiler can transform the app, and then it can be removed.
         *
         * - If `false`, the compiler will inject the `useIntlayer()` function call into the code in the build output only, and keep the base codebase intact. The transformation will be done only in memory.
         */
        saveComponents: false,
    
        /**
         * Dictionary key prefix
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Extract commandBabel compiler

    Run the extractor to transform your components and extract the content

    bash

    نسخ المحتوى

    نسخ الكود

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

    npx intlayer extract
    

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

    Update your vite.config.ts to include the intlayerCompiler plugin:

    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 # Or npm run dev
    

    ---

تكوين TypeScript

تستخدم Intlayer تقنية توسيع الوحدات (module augmentation) للاستفادة من TypeScript، مما يجعل برمجتك أكثر قوة.

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

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

تكوين Git

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

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

# تجاهل الملفات المولدة بواسطة Intlayer
.intlayer

إضافة VS Code

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

التثبيت من VS Code Marketplace

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

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

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

تعمق أكثر

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