خريطة الموقع XML و Hreflang — دليل المطور وواجهة الإدارة
1. التثبيت وإعداد الاعتماديات
Section titled “1. التثبيت وإعداد الاعتماديات”pnpm add @vicacha-devs/strapi-plugin-sitemap2. إعدادات الخادم (config/plugins.ts)
Section titled “2. إعدادات الخادم (config/plugins.ts)”أضف إعدادات الإضافة إلى ملف config/plugins.ts في مشروع Strapi v5 الخاص بك:
export default ({ env }: { env: (key: string, defaultValue?: string) => string }) => ({ "sitemap": { enabled: true, config: { hostname: env("SITEMAP_HOSTNAME", "https://example.org"), includeHreflang: true, }, },});
3. جولة في واجهة الإدارة (Strapi v5 Admin UI — دعم RTL)
Section titled “3. جولة في واجهة الإدارة (Strapi v5 Admin UI — دعم RTL)”بمجرد تفعيل الإضافة، يتم تسجيل مساحة العمل والإعدادات داخل لوحة تحكم Strapi v5 مع دعم كامل للغة العربية واتجاه RTL:

نماذج من نصوص الواجهة المعربة (العربية)
Section titled “نماذج من نصوص الواجهة المعربة (العربية)”| مفتاح الترجمة | النص المعروض في الواجهة |
|---|---|
plugin.name |
خريطة الموقع |
plugin.section.item |
الإعدادات |
settings.title |
خريطة الموقع (Sitemap) |
settings.subtitle |
إعدادات ملف XML لخريطة الموقع وفهرس الخرائط |
settings.showSitemap |
عرض خريطة الموقع |
settings.baseUrl.title |
الرابط الأساسي (Base URL) |
settings.baseUrl.description |
أدخل الرابط الأساسي المستخدم لجميع عناصر خريطة الموقع |
settings.baseUrl.placeholder |
https://example.com |
4. كيانات أنواع المحتوى ومواقعها ومخططاتها (strapi.documents)
Section titled “4. كيانات أنواع المحتوى ومواقعها ومخططاتها (strapi.documents)”Registers two internal Collection Types (plugin::sitemap.sitemap-content-type and plugin::sitemap.sitemap-content-type-single-url) and one Single Type (plugin::sitemap.sitemap-option) with content-manager.visible: false, while introspecting all public api::* and plugin::* Content-Type entities to generate /api/sitemap/sitemap.xml and /api/sitemap/sitemap-{slug}.xml.
أين تجد كيانات أنواع المحتوى في Strapi v5
Section titled “أين تجد كيانات أنواع المحتوى في Strapi v5”- Settings Panel (4 Tabs):
/admin/settings/sitemap(Settings -> Sitemap -> Configuration— organized into General & Sitemap Index, Collection Types, Custom URLs, and Excluded URLs tabs) - Internal Persistence Entities:
plugin::sitemap.sitemap-content-type(strapi_5_sitemap_plugin_content_types),plugin::sitemap.sitemap-content-type-single-url(strapi_5_sitemap_plugin_content_type_single_urls), andplugin::sitemap.sitemap-option(strapi_5_sitemap_plugin_options)
plugin::sitemap.sitemap-content-type — Sitemap Content Type
Section titled “plugin::sitemap.sitemap-content-type — Sitemap Content Type”Per-locale URL pattern, priority, and changefreq mapping for a Strapi Content-Type entity
Kind:
collectionType· DB Table:strapi_5_sitemap_plugin_content_types· Admin Location: Internal (/admin/plugins/sitemap) · Draft & Publish:No· i18n:No
| الحقل | النوع في Strapi | إلزامي | القيود / العلاقات |
|---|---|---|---|
type |
string |
No | — |
langcode |
string |
No | — |
pattern |
string |
No | — |
priority |
float |
No | — |
frequency |
string |
No | — |
lastModified |
string |
No | — |
thumbnail |
string |
No | — |
populateLinkedModels |
string |
No | — |
plugin::sitemap.sitemap-content-type-single-url — Sitemap Single URL
Section titled “plugin::sitemap.sitemap-content-type-single-url — Sitemap Single URL”Custom static URL entry included alongside dynamic CMS entries in sitemap.xml
Kind:
collectionType· DB Table:strapi_5_sitemap_plugin_content_type_single_urls· Admin Location: Internal (/admin/plugins/sitemap) · Draft & Publish:No· i18n:No
| الحقل | النوع في Strapi | إلزامي | القيود / العلاقات |
|---|---|---|---|
slug |
string |
No | — |
priority |
float |
No | — |
frequency |
string |
No | — |
plugin::sitemap.sitemap-option — Sitemap Options
Section titled “plugin::sitemap.sitemap-option — Sitemap Options”Global sitemap configuration (baseUrl, excludedUrls, useSitemapIndex, sitemapDefinitions)
Kind:
singleType· DB Table:strapi_5_sitemap_plugin_options· Admin Location: Internal (/admin/plugins/sitemap) · Draft & Publish:No· i18n:No
| الحقل | النوع في Strapi | إلزامي | القيود / العلاقات |
|---|---|---|---|
baseUrl |
string |
No | — |
excludedUrls |
json |
No | default: [] |
useSitemapIndex |
boolean |
No | default: false |
sitemapDefinitions |
json |
No | default: [] |
التكامل مع مدير المحتوى في Strapi v5 (/admin/content-manager)
Section titled “التكامل مع مدير المحتوى في Strapi v5 (/admin/content-manager)”مجموعة الشريط الجانبي في مدير المحتوى:
Maps All Public Content Manager Collection Types & Single Types
الكيانات والمكونات المسجلة في مدير المحتوى
Section titled “الكيانات والمكونات المسجلة في مدير المحتوى”plugin::sitemap.sitemap-content-type(Internal URL pattern mapping for Content Manager entities)plugin::sitemap.sitemap-content-type-single-url(Internal custom static URL entries)plugin::sitemap.sitemap-option(Internal global sitemap settings)

لماذا تنشئ هذه الإضافة كيانات داخل مدير المحتوى (Content Manager)؟
Section titled “لماذا تنشئ هذه الإضافة كيانات داخل مدير المحتوى (Content Manager)؟”@vicacha-devs/strapi-plugin-sitemap keeps its 3 configuration schemas (sitemap-content-type, sitemap-content-type-single-url, sitemap-option) hidden from the Content Manager sidebar (content-manager.visible: false) to prevent accidental schema edits, while dynamically reading published documents and i18n localizations from every public Content Manager Collection Type (api::* and plugin::*):
- Automatic Sync with Content Manager Publishing: Whenever an editor publishes, updates, or unpublishes an
Article,Event,Donation Campaign, orResource Publicationin Content Manager,/api/sitemap/sitemap.xmlautomatically reflects itslastmodandxhtml:linkhreflangalternates.
كيفية الاستخدام داخل مدير المحتوى في Strapi (خطوة بخطوة)
Section titled “كيفية الاستخدام داخل مدير المحتوى في Strapi (خطوة بخطوة)”- Publish Content in Content Manager: Author and publish localized entries in any
api::*orplugin::*collection inside/admin/content-manager. - Map URL Patterns in Sitemap Settings: Open
/admin/settings/sitemap-> Collection Types tab and bind each Content Manager collection UID + locale to its frontend route pattern (e.g.,/[locale]/articles/[slug]). - Configure Sitemap Index, Custom & Excluded URLs: Use the General & Sitemap Index tab (
Use sitemap index with multiple sitemaps+getSitemapBySlug in Users & Permissions → Public → Sitemap), Custom URLs tab, and Excluded URLs tab in/admin/settings/sitemap.
التزامن بين مدير المحتوى ومساحة عمل الإضافة
Section titled “التزامن بين مدير المحتوى ومساحة عمل الإضافة”حالات الاستخدام داخل مدير المحتوى ومسارات العمل التحريرية
Section titled “حالات الاستخدام داخل مدير المحتوى ومسارات العمل التحريرية”Content Manager Use Case 1 — Auto-Syndicating Published Content Manager Entries to Multilingual XML Sitemaps
Section titled “Content Manager Use Case 1 — Auto-Syndicating Published Content Manager Entries to Multilingual XML Sitemaps”- الغرض والأهمية: Ensure every newly published localized Event, Article, or Publication in Content Manager is immediately indexed with
hreflangalternates. - خطوات التنفيذ في مدير المحتوى: Publish the entry across
es,en,ar, andtrin/admin/content-managerand verify its<url>block inGET /api/sitemap/sitemap.xml.
5. حالات الاستخدام ومسارات العمل المتكاملة
Section titled “5. حالات الاستخدام ومسارات العمل المتكاملة”Use Case 1 — Dynamic Multilingual Entity URL Pattern Mapping & xhtml:link Hreflang
Section titled “Use Case 1 — Dynamic Multilingual Entity URL Pattern Mapping & xhtml:link Hreflang”- What it is for: Map any localized Strapi Content-Type entity (
api::article.article,plugin::events.event,plugin::resources.publication) to dynamic URL patterns with automatichreflangalternates. - How it works: In
/admin/settings/sitemap(Collection Types tab), map a content type +langcodeto a pattern (e.g.,/[locale]/articles/[slug]),priority, andfrequency(plugin::sitemap.sitemap-content-type).

Use Case 2 — Hybrid Static + CMS Sitemap with Custom Single URLs & Excluded Paths
Section titled “Use Case 2 — Hybrid Static + CMS Sitemap with Custom Single URLs & Excluded Paths”- What it is for: Include static frontend routes (
/es,/es/about-us,/en/about-us) alongside dynamic CMS entries in the same XML sitemap while excluding internal paths (/admin,/api,/404). - How it works: Add static route entries in the Custom URLs tab (
plugin::sitemap.sitemap-content-type-single-url) and exclude internal routes in the Excluded URLs tab of/admin/settings/sitemap.

Use Case 3 — Multi-File Sitemap Index (sitemap-{slug}.xml) for Large Sites
Section titled “Use Case 3 — Multi-File Sitemap Index (sitemap-{slug}.xml) for Large Sites”- What it is for: Split large portals into dedicated sub-sitemaps (e.g.,
/api/sitemap/sitemap-pages.xml,/api/sitemap/sitemap-editorial-and-library.xml,/api/sitemap/sitemap-events-and-liturgy.xml) referenced by a master<sitemapindex>. - How it works: Enable Use sitemap index with multiple sitemaps (
useSitemapIndex: true), grantgetSitemapBySluginUsers & Permissions → Public → Sitemap, and definesitemapDefinitionsin the General & Sitemap Index tab of/admin/settings/sitemap(PUT /sitemap/settings).

6. نقاط النهاية البرمجية REST API (content-api و admin)
Section titled “6. نقاط النهاية البرمجية REST API (content-api و admin)”| الطريقة | مسار نقطة النهاية | النطاق | المعالج (Handler) | المصادقة |
|---|---|---|---|---|
GET |
/api/sitemap/sitemap.xml |
content-api |
controller.getSitemap |
Bearer JWT |
GET |
/api/sitemap/sitemap-{slug}.xml |
content-api |
controller.getSitemapBySlug |
Bearer JWT |
GET |
/sitemap/settings |
admin |
controller.getSettings |
Bearer JWT |
PUT |
/sitemap/settings |
admin |
controller.updateSettings |
Bearer JWT |
GET |
/sitemap/content-types |
admin |
controller.getContentTypes |
Bearer JWT |
GET |
/sitemap/locales |
admin |
controller.getLocales |
Bearer JWT |
GET |
/sitemap/allowed-fields |
admin |
controller.getAllowedFields |
Bearer JWT |
7. الاستخدام البرمجي داخل الخادم (strapi.plugin و strapi.documents)
Section titled “7. الاستخدام البرمجي داخل الخادم (strapi.plugin و strapi.documents)”// Registered services on plugin "sitemap": "service", "settings"const pluginService = strapi.plugin("sitemap")?.service("service");
// Querying records via the Strapi v5 Document Service APIconst records = await strapi.documents("plugin::sitemap.sitemap-content-type").findMany({ limit: 25, sort: "createdAt:desc",});8. استكشاف الأخطاء والتحقق من الجودة
Section titled “8. استكشاف الأخطاء والتحقق من الجودة”- عدم ظهور التغييرات في لوحة الإدارة: قم بتشغيل
pnpm strapi buildبعد تعديل ملفconfig/plugins.ts. - عزل حزم Strapi: حافظ على إعداد
hoistPattern: ["*", "!@strapi/*"]داخلpnpm-workspace.yamlلمنع تكرار سياق React. - فحص الأنواع الصارم (TypeScript): قم بتشغيل
pnpm checkللتحقق من سلامة حزمتي الواجهة والخادم.