From dafb58f89778116c0cb96d0065dad1e4f071ac0a Mon Sep 17 00:00:00 2001 From: xiaoyu2er Date: Mon, 2 Jun 2025 19:49:24 +0000 Subject: [PATCH] docs: update documentation translations --- .../ar/blog/building-apis-with-nextjs.mdx | 502 ++++++++++ .../content/ar/blog/composable-caching.mdx | 202 ++++ apps/docs/content/ar/blog/create-next-app.mdx | 38 + .../content/ar/blog/incremental-adoption.mdx | 109 +++ .../docs/content/ar/blog/june-2023-update.mdx | 147 +++ apps/docs/content/ar/blog/layouts-rfc.mdx | 910 ++++++++++++++++++ apps/docs/content/ar/blog/next-10-1.mdx | 229 +++++ apps/docs/content/ar/blog/next-10-2.mdx | 182 ++++ apps/docs/content/ar/blog/next-10.mdx | 428 ++++++++ apps/docs/content/ar/blog/next-11-1.mdx | 181 ++++ apps/docs/content/ar/blog/next-11.mdx | 218 +++++ apps/docs/content/ar/blog/next-12-1.mdx | 218 +++++ apps/docs/content/ar/blog/next-12-2.mdx | 271 ++++++ apps/docs/content/ar/blog/next-12.mdx | 270 ++++++ apps/docs/content/ar/blog/next-13-1.mdx | 216 +++++ apps/docs/content/ar/blog/next-13-2.mdx | 373 +++++++ apps/docs/content/ar/blog/next-13-3.mdx | 272 ++++++ apps/docs/content/ar/blog/next-13-4.mdx | 461 +++++++++ apps/docs/content/ar/blog/next-13-5.mdx | 179 ++++ apps/docs/content/ar/blog/next-13.mdx | 429 +++++++++ apps/docs/content/ar/blog/next-14-1.mdx | 271 ++++++ apps/docs/content/ar/blog/next-14-2.mdx | 218 +++++ apps/docs/content/ar/blog/next-14.mdx | 297 ++++++ apps/docs/content/ar/blog/next-15-1.mdx | 293 ++++++ apps/docs/content/ar/blog/next-15-2.mdx | 229 +++++ apps/docs/content/ar/blog/next-15-3.mdx | 206 ++++ apps/docs/content/ar/blog/next-15-rc.mdx | 346 +++++++ apps/docs/content/ar/blog/next-15-rc2.mdx | 404 ++++++++ apps/docs/content/ar/blog/next-15.mdx | 571 +++++++++++ apps/docs/content/ar/blog/next-5-1.mdx | 183 ++++ apps/docs/content/ar/blog/next-5.mdx | 361 +++++++ apps/docs/content/ar/blog/next-6-1.mdx | 141 +++ apps/docs/content/ar/blog/next-6.mdx | 175 ++++ apps/docs/content/ar/blog/next-7.mdx | 387 ++++++++ apps/docs/content/ar/blog/next-8-0-4.mdx | 173 ++++ apps/docs/content/ar/blog/next-8-1.mdx | 145 +++ apps/docs/content/ar/blog/next-8.mdx | 349 +++++++ apps/docs/content/ar/blog/next-9-0-7.mdx | 255 +++++ apps/docs/content/ar/blog/next-9-1-7.mdx | 216 +++++ apps/docs/content/ar/blog/next-9-1.mdx | 196 ++++ apps/docs/content/ar/blog/next-9-2.mdx | 218 +++++ apps/docs/content/ar/blog/next-9-3.mdx | 534 ++++++++++ apps/docs/content/ar/blog/next-9-4.mdx | 297 ++++++ apps/docs/content/ar/blog/next-9-5.mdx | 397 ++++++++ apps/docs/content/ar/blog/next-9.mdx | 438 +++++++++ .../ar/blog/our-journey-with-caching.mdx | 219 +++++ ...urity-nextjs-server-components-actions.mdx | 393 ++++++++ .../ar/blog/styling-next-with-styled-jsx.mdx | 371 +++++++ .../blog/turbopack-for-development-stable.mdx | 294 ++++++ apps/docs/content/ar/blog/webpack-memory.mdx | 95 ++ .../01-what-is-react-and-nextjs.mdx | 71 ++ .../01-react-foundations/02-rendering-ui.mdx | 45 + .../03-updating-ui-with-javascript.mdx | 137 +++ .../04-getting-started-with-react.mdx | 148 +++ .../05-building-ui-with-components.mdx | 191 ++++ .../06-displaying-data-with-props.mdx | 253 +++++ .../07-updating-state.mdx | 199 ++++ .../08-from-react-to-nextjs.mdx | 68 ++ .../01-react-foundations/09-installation.mdx | 179 ++++ .../10-server-and-client-components.mdx | 166 ++++ .../ar/learn/01-react-foundations/index.mdx | 31 + .../02-dashboard-app/01-getting-started.mdx | 144 +++ .../learn/02-dashboard-app/02-css-styling.mdx | 179 ++++ .../03-optimizing-fonts-images.mdx | 203 ++++ .../04-creating-layouts-and-pages.mdx | 151 +++ .../05-navigating-between-pages.mdx | 152 +++ .../06-setting-up-your-database.mdx | 131 +++ .../02-dashboard-app/07-fetching-data.mdx | 303 ++++++ .../08-static-and-dynamic-rendering.mdx | 78 ++ .../learn/02-dashboard-app/09-streaming.mdx | 348 +++++++ .../10-partial-prerendering.mdx | 110 +++ .../11-adding-search-and-pagination.mdx | 558 +++++++++++ .../02-dashboard-app/12-mutating-data.mdx | 659 +++++++++++++ .../02-dashboard-app/13-error-handling.mdx | 203 ++++ .../14-improving-accessibility.mdx | 369 +++++++ .../15-adding-authentication.mdx | 476 +++++++++ .../02-dashboard-app/16-adding-metadata.mdx | 163 ++++ .../ar/learn/02-dashboard-app/index.mdx | 69 ++ .../01-create-nextjs-app-setup.mdx | 45 + ...02-create-nextjs-app-welcome-to-nextjs.mdx | 15 + .../03-create-nextjs-app-editing-the-page.mdx | 28 + .../04-navigate-between-pages.mdx | 22 + .../05-navigate-between-pages-setup.mdx | 21 + ...navigate-between-pages-pages-in-nextjs.mdx | 42 + ...-navigate-between-pages-link-component.mdx | 60 ++ .../08-navigate-between-pages-client-side.mdx | 43 + ...9-assets-metadata-css-layout-component.mdx | 87 ++ .../10-assets-metadata-css.mdx | 30 + .../11-assets-metadata-css-setup.mdx | 21 + .../12-assets-metadata-css-assets.mdx | 74 ++ .../13-assets-metadata-css-metadata.mdx | 58 ++ ...ts-metadata-css-third-party-javascript.mdx | 78 ++ .../15-assets-metadata-css-css-styling.mdx | 29 + .../16-assets-metadata-css-global-styles.mdx | 97 ++ ...7-assets-metadata-css-polishing-layout.mdx | 214 ++++ .../18-assets-metadata-css-styling-tips.mdx | 107 ++ .../19-data-fetching-blog-data.mdx | 130 +++ .../03-pages-router/20-data-fetching.mdx | 20 + .../21-data-fetching-setup.mdx | 27 + .../22-data-fetching-pre-rendering.mdx | 40 + .../23-data-fetching-two-forms.mdx | 46 + .../24-data-fetching-with-data.mdx | 48 + ...data-fetching-implement-getstaticprops.mdx | 80 ++ ...6-data-fetching-getstaticprops-details.mdx | 59 ++ .../27-data-fetching-request-time.mdx | 67 ++ .../03-pages-router/28-dynamic-routes.mdx | 20 + .../29-dynamic-routes-setup.mdx | 27 + ...dynamic-routes-page-path-external-data.mdx | 75 ++ ...ynamic-routes-implement-getstaticpaths.mdx | 73 ++ ...ynamic-routes-implement-getstaticprops.mdx | 96 ++ .../33-dynamic-routes-render-markdown.mdx | 91 ++ .../34-dynamic-routes-polishing-post-page.mdx | 105 ++ ...35-dynamic-routes-polishing-index-page.mdx | 37 + ...-dynamic-routes-dynamic-routes-details.mdx | 112 +++ .../learn/03-pages-router/37-api-routes.mdx | 16 + .../03-pages-router/38-api-routes-setup.mdx | 27 + .../39-api-routes-creating-api-routes.mdx | 37 + .../40-api-routes-api-routes-details.mdx | 40 + .../41-deploying-nextjs-app.mdx | 22 + .../42-deploying-nextjs-app-setup.mdx | 27 + .../43-deploying-nextjs-app-github.mdx | 27 + .../44-deploying-nextjs-app-deploy.mdx | 38 + ...-deploying-nextjs-app-platform-details.mdx | 55 ++ ...oying-nextjs-app-other-hosting-options.mdx | 37 + .../ar/learn/03-pages-router/index.mdx | 53 + .../ar/learn/04-seo/01-importance-of-seo.mdx | 28 + .../ar/learn/04-seo/02-search-systems.mdx | 18 + .../ar/learn/04-seo/03-webcrawlers.mdx | 43 + .../learn/04-seo/04-crawling-and-indexing.mdx | 16 + .../ar/learn/04-seo/05-status-codes.mdx | 132 +++ .../content/ar/learn/04-seo/06-robots-txt.mdx | 36 + .../ar/learn/04-seo/07-xml-sitemaps.mdx | 107 ++ .../content/ar/learn/04-seo/08-metatags.mdx | 96 ++ .../content/ar/learn/04-seo/09-canonical.mdx | 61 ++ .../learn/04-seo/10-rendering-and-ranking.mdx | 19 + .../learn/04-seo/11-rendering-strategies.mdx | 41 + apps/docs/content/ar/learn/04-seo/12-amp.mdx | 15 + .../ar/learn/04-seo/13-url-structure.mdx | 122 +++ .../content/ar/learn/04-seo/14-metadata.mdx | 212 ++++ .../ar/learn/04-seo/15-on-page-seo.mdx | 81 ++ .../ar/learn/04-seo/16-web-performance.mdx | 23 + .../ar/learn/04-seo/17-vitals-overview.mdx | 24 + apps/docs/content/ar/learn/04-seo/18-lcp.mdx | 27 + apps/docs/content/ar/learn/04-seo/19-fid.mdx | 23 + apps/docs/content/ar/learn/04-seo/20-cls.mdx | 25 + .../content/ar/learn/04-seo/21-seo-impact.mdx | 40 + .../content/ar/learn/04-seo/22-improve.mdx | 19 + .../content/ar/learn/04-seo/23-lighthouse.mdx | 70 ++ .../content/ar/learn/04-seo/24-images.mdx | 85 ++ .../ar/learn/04-seo/25-dynamic-imports.mdx | 70 ++ .../04-seo/26-dynamic-import-components.mdx | 66 ++ .../docs/content/ar/learn/04-seo/27-fonts.mdx | 27 + .../learn/04-seo/28-third-party-scripts.mdx | 54 ++ .../content/ar/learn/04-seo/29-monitor.mdx | 17 + .../learn/04-seo/30-nextjs-speed-insights.mdx | 14 + .../ar/learn/04-seo/31-custom-reporting.mdx | 41 + .../ar/learn/04-seo/32-other-tools.mdx | 20 + .../ar/learn/04-seo/33-data-studio.mdx | 26 + apps/docs/content/ar/learn/04-seo/index.mdx | 28 + 159 files changed, 24620 insertions(+) create mode 100644 apps/docs/content/ar/blog/building-apis-with-nextjs.mdx create mode 100644 apps/docs/content/ar/blog/composable-caching.mdx create mode 100644 apps/docs/content/ar/blog/create-next-app.mdx create mode 100644 apps/docs/content/ar/blog/incremental-adoption.mdx create mode 100644 apps/docs/content/ar/blog/june-2023-update.mdx create mode 100644 apps/docs/content/ar/blog/layouts-rfc.mdx create mode 100644 apps/docs/content/ar/blog/next-10-1.mdx create mode 100644 apps/docs/content/ar/blog/next-10-2.mdx create mode 100644 apps/docs/content/ar/blog/next-10.mdx create mode 100644 apps/docs/content/ar/blog/next-11-1.mdx create mode 100644 apps/docs/content/ar/blog/next-11.mdx create mode 100644 apps/docs/content/ar/blog/next-12-1.mdx create mode 100644 apps/docs/content/ar/blog/next-12-2.mdx create mode 100644 apps/docs/content/ar/blog/next-12.mdx create mode 100644 apps/docs/content/ar/blog/next-13-1.mdx create mode 100644 apps/docs/content/ar/blog/next-13-2.mdx create mode 100644 apps/docs/content/ar/blog/next-13-3.mdx create mode 100644 apps/docs/content/ar/blog/next-13-4.mdx create mode 100644 apps/docs/content/ar/blog/next-13-5.mdx create mode 100644 apps/docs/content/ar/blog/next-13.mdx create mode 100644 apps/docs/content/ar/blog/next-14-1.mdx create mode 100644 apps/docs/content/ar/blog/next-14-2.mdx create mode 100644 apps/docs/content/ar/blog/next-14.mdx create mode 100644 apps/docs/content/ar/blog/next-15-1.mdx create mode 100644 apps/docs/content/ar/blog/next-15-2.mdx create mode 100644 apps/docs/content/ar/blog/next-15-3.mdx create mode 100644 apps/docs/content/ar/blog/next-15-rc.mdx create mode 100644 apps/docs/content/ar/blog/next-15-rc2.mdx create mode 100644 apps/docs/content/ar/blog/next-15.mdx create mode 100644 apps/docs/content/ar/blog/next-5-1.mdx create mode 100644 apps/docs/content/ar/blog/next-5.mdx create mode 100644 apps/docs/content/ar/blog/next-6-1.mdx create mode 100644 apps/docs/content/ar/blog/next-6.mdx create mode 100644 apps/docs/content/ar/blog/next-7.mdx create mode 100644 apps/docs/content/ar/blog/next-8-0-4.mdx create mode 100644 apps/docs/content/ar/blog/next-8-1.mdx create mode 100644 apps/docs/content/ar/blog/next-8.mdx create mode 100644 apps/docs/content/ar/blog/next-9-0-7.mdx create mode 100644 apps/docs/content/ar/blog/next-9-1-7.mdx create mode 100644 apps/docs/content/ar/blog/next-9-1.mdx create mode 100644 apps/docs/content/ar/blog/next-9-2.mdx create mode 100644 apps/docs/content/ar/blog/next-9-3.mdx create mode 100644 apps/docs/content/ar/blog/next-9-4.mdx create mode 100644 apps/docs/content/ar/blog/next-9-5.mdx create mode 100644 apps/docs/content/ar/blog/next-9.mdx create mode 100644 apps/docs/content/ar/blog/our-journey-with-caching.mdx create mode 100644 apps/docs/content/ar/blog/security-nextjs-server-components-actions.mdx create mode 100644 apps/docs/content/ar/blog/styling-next-with-styled-jsx.mdx create mode 100644 apps/docs/content/ar/blog/turbopack-for-development-stable.mdx create mode 100644 apps/docs/content/ar/blog/webpack-memory.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/01-what-is-react-and-nextjs.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/02-rendering-ui.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/03-updating-ui-with-javascript.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/04-getting-started-with-react.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/05-building-ui-with-components.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/06-displaying-data-with-props.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/07-updating-state.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/08-from-react-to-nextjs.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/09-installation.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/10-server-and-client-components.mdx create mode 100644 apps/docs/content/ar/learn/01-react-foundations/index.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/01-getting-started.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/02-css-styling.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/03-optimizing-fonts-images.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/04-creating-layouts-and-pages.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/05-navigating-between-pages.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/06-setting-up-your-database.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/07-fetching-data.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/08-static-and-dynamic-rendering.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/09-streaming.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/10-partial-prerendering.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/11-adding-search-and-pagination.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/12-mutating-data.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/13-error-handling.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/14-improving-accessibility.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/15-adding-authentication.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/16-adding-metadata.mdx create mode 100644 apps/docs/content/ar/learn/02-dashboard-app/index.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/01-create-nextjs-app-setup.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/02-create-nextjs-app-welcome-to-nextjs.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/03-create-nextjs-app-editing-the-page.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/04-navigate-between-pages.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/05-navigate-between-pages-setup.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/06-navigate-between-pages-pages-in-nextjs.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/07-navigate-between-pages-link-component.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/08-navigate-between-pages-client-side.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/09-assets-metadata-css-layout-component.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/10-assets-metadata-css.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/11-assets-metadata-css-setup.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/12-assets-metadata-css-assets.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/13-assets-metadata-css-metadata.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/14-assets-metadata-css-third-party-javascript.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/15-assets-metadata-css-css-styling.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/16-assets-metadata-css-global-styles.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/17-assets-metadata-css-polishing-layout.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/18-assets-metadata-css-styling-tips.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/19-data-fetching-blog-data.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/20-data-fetching.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/21-data-fetching-setup.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/22-data-fetching-pre-rendering.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/23-data-fetching-two-forms.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/24-data-fetching-with-data.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/25-data-fetching-implement-getstaticprops.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/26-data-fetching-getstaticprops-details.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/27-data-fetching-request-time.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/28-dynamic-routes.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/29-dynamic-routes-setup.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/30-dynamic-routes-page-path-external-data.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/31-dynamic-routes-implement-getstaticpaths.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/32-dynamic-routes-implement-getstaticprops.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/33-dynamic-routes-render-markdown.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/34-dynamic-routes-polishing-post-page.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/35-dynamic-routes-polishing-index-page.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/36-dynamic-routes-dynamic-routes-details.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/37-api-routes.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/38-api-routes-setup.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/39-api-routes-creating-api-routes.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/40-api-routes-api-routes-details.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/41-deploying-nextjs-app.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/42-deploying-nextjs-app-setup.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/43-deploying-nextjs-app-github.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/44-deploying-nextjs-app-deploy.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/45-deploying-nextjs-app-platform-details.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/46-deploying-nextjs-app-other-hosting-options.mdx create mode 100644 apps/docs/content/ar/learn/03-pages-router/index.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/01-importance-of-seo.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/02-search-systems.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/03-webcrawlers.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/04-crawling-and-indexing.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/05-status-codes.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/06-robots-txt.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/07-xml-sitemaps.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/08-metatags.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/09-canonical.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/10-rendering-and-ranking.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/11-rendering-strategies.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/12-amp.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/13-url-structure.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/14-metadata.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/15-on-page-seo.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/16-web-performance.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/17-vitals-overview.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/18-lcp.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/19-fid.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/20-cls.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/21-seo-impact.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/22-improve.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/23-lighthouse.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/24-images.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/25-dynamic-imports.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/26-dynamic-import-components.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/27-fonts.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/28-third-party-scripts.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/29-monitor.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/30-nextjs-speed-insights.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/31-custom-reporting.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/32-other-tools.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/33-data-studio.mdx create mode 100644 apps/docs/content/ar/learn/04-seo/index.mdx diff --git a/apps/docs/content/ar/blog/building-apis-with-nextjs.mdx b/apps/docs/content/ar/blog/building-apis-with-nextjs.mdx new file mode 100644 index 00000000..b31f76d4 --- /dev/null +++ b/apps/docs/content/ar/blog/building-apis-with-nextjs.mdx @@ -0,0 +1,502 @@ +--- +source-updated-at: 2025-05-29T18:05:49.000Z +translation-updated-at: 2025-06-02T19:44:47.947Z +title: بناء واجهات برمجة التطبيقات (APIs) باستخدام Next.js +description: تعرف على كيفية بناء واجهات برمجة التطبيقات (APIs) باستخدام Next.js. +author: + - name: لي روبنسون + image: /static/team/lee.jpg +date: 2025-02-28T14:00:00.507Z +image: >- + https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/building-apis-with-nextjs/twitter-card.png +--- + +سيتناول هذا الدليل كيفية بناء واجهات برمجة التطبيقات (APIs) باستخدام Next.js، بما في ذلك إعداد المشروع، فهم موجه التطبيق (App Router) ومعالجات المسارات (Route Handlers)، التعامل مع طرق HTTP المتعددة، تنفيذ التوجيه الديناميكي، إنشاء منطق وسيط قابل لإعادة الاستخدام، واتخاذ قرار بشأن الوقت المناسب لإنشاء طبقة API مخصصة. + +* [1. البدء](#1-getting-started) + * [1.1 إنشاء تطبيق Next.js](#11-create-a-nextjs-app) + * [1.2 موجه التطبيق (App Router) مقابل موجه الصفحات (Pages Router)](#12-app-router-vs-pages-router) +* [2. لماذا (ومتى) تبني واجهات برمجة التطبيقات باستخدام Next.js](#2-why-and-when-to-build-apis-with-nextjs) +* [3. إنشاء واجهة برمجة تطبيقات باستخدام معالجات المسارات (Route Handlers)](#3-creating-an-api-with-route-handlers) + * [3.1 إعداد الملف الأساسي](#31-basic-file-setup) + * [3.2 طرق HTTP متعددة في ملف واحد](#32-multiple-http-methods-in-one-file) +* [4. العمل مع واجهات برمجة تطبيقات الويب (Web APIs)](#4-working-with-web-apis) + * [4.1 استخدام Request و Response مباشرة](#41-directly-using-request--response) + * [4.2 معاملات الاستعلام (Query parameters)](#42-query-parameters) + * [4.3 الرؤوس (Headers) وملفات تعريف الارتباط (Cookies)](#43-headers-and-cookies) +* [5. المسارات الديناميكية](#5-dynamic-routes) +* [6. استخدام Next.js كطبقة وكيل (proxy) أو توجيه](#6-using-nextjs-as-a-proxy-or-forwarding-layer) +* [7. بناء منطق "وسيط" مشترك](#7-building-shared-middleware-logic) +* [8. اعتبارات النشر ووضع "تطبيق الصفحة الواحدة (SPA)"](#8-deployment-and-spa-mode-considerations) + * [8.1 النشر القياسي لـ Node.js](#81-standard-nodejs-deployment) + * [8.2 تصدير ثابت/وضع تطبيق الصفحة الواحدة (SPA/Static Export)](#82-spastatic-export) + * [8.3 نشر واجهات برمجة التطبيقات على Vercel](#83-deploying-apis-on-vercel) +* [9. متى تتخطى إنشاء نقطة نهاية لواجهة برمجة التطبيقات](#9-when-to-skip-creating-an-api-endpoint) +* [10. جمع كل شيء معًا](#10-putting-it-all-together) +* [الختام](#conclusion) +* [الأسئلة الشائعة](#frequently-asked-questions) + * [ماذا عن إجراءات الخادم (Server Actions)؟](#what-about-server-actions) + * [هل يمكنني استخدام TypeScript مع معالجات المسارات (Route Handlers)؟](#can-i-use-typescript-with-route-handlers) + * [ما هي أفضل الممارسات للمصادقة (Authentication)؟](#what-are-the-best-practices-for-authentication) + +[1. البدء](#1-getting-started) +----------------------------------------- + +### [1.1 إنشاء تطبيق Next.js](#11-create-a-nextjs-app) + +إذا كنت تبدأ من الصفر، يمكنك إنشاء مشروع Next.js جديد باستخدام: + +```bash filename="Terminal" +npx create-next-app@latest --api +``` + +> **ملاحظة:** تحدد العلامة `--api` تلقائيًا مثالًا لملف `route.ts` في مجلد `app/` الخاص بمشروعك الجديد، لتوضيح كيفية إنشاء نقطة نهاية لواجهة برمجة التطبيقات. + +### [1.2 موجه التطبيق (App Router) مقابل موجه الصفحات (Pages Router)](#12-app-router-vs-pages-router) + +* **موجه الصفحات (Pages Router)**: تاريخيًا، استخدم Next.js `pages/api/*` لواجهات برمجة التطبيقات. اعتمد هذا النهج على كائنات طلب/استجابة Node.js وواجهة برمجة تطبيقات تشبه Express. +* **موجه التطبيق (App Router) (الافتراضي)**: تم تقديمه في Next.js 13، يعتمد موجه التطبيق بالكامل على واجهات برمجة تطبيقات طلب/استجابة الويب القياسية. بدلاً من `pages/api/*`، يمكنك الآن وضع ملفات `route.ts` أو `route.js` في أي مكان داخل دليل `app/`. + +> **لماذا التبديل؟** تعتمد "معالجات المسارات (Route Handlers)" في موجه التطبيق على [واجهات برمجة تطبيقات طلب/استجابة منصة الويب](https://developer.mozilla.org/en-US/docs/Web/API) بدلاً من واجهات برمجة تطبيقات محددة لـ Node.js. هذا يبسط التعلم، ويقلل الاحتكاك، ويساعدك على إعادة استخدام معرفتك عبر أدوات مختلفة. + +[2. لماذا (ومتى) تبني واجهات برمجة التطبيقات باستخدام Next.js](#2-why-and-when-to-build-apis-with-nextjs) +------------------------------------------------------------------------------------------ + +1. **واجهة برمجة تطبيقات عامة لعملاء متعددين** + + * يمكنك بناء واجهة برمجة تطبيقات عامة يتم استهلاكها بواسطة تطبيق الويب Next.js الخاص بك، أو تطبيق جوال منفصل، أو أي خدمة تابعة لجهة خارجية. على سبيل المثال، قد تجلب البيانات من `/api/users` في كل من موقع React الخاص بك وتطبيق React Native للجوال. +2. **وكيل لخلفية موجودة** + + * في بعض الأحيان تريد إخفاء أو دمج [الخدمات المصغرة (microservices)](https://vercel.com/blog/how-vercel-adopted-microfrontends) الخارجية خلف نقطة نهاية واحدة. يمكن أن تعمل معالجات المسارات (Route Handlers) في Next.js كطبقة وسيطة أو وكيل لخلفية موجودة. على سبيل المثال، يمكنك اعتراض الطلبات، والتعامل مع المصادقة، وتحويل البيانات، ثم تمرير الطلب إلى واجهة برمجة تطبيقات المصدر. +3. **الخطافات الويب (Webhooks) والتكاملات** + + * إذا كنت تتلقى ردود اتصال أو خطافات ويب خارجية (مثل من Stripe أو GitHub أو Twilio)، فيمكنك التعامل معها باستخدام معالجات المسارات (Route Handlers). +4. **مصادقة مخصصة** + + * إذا كنت بحاجة إلى جلسات أو رموز أو منطق مصادقة آخر، فيمكنك تخزين ملفات تعريف الارتباط، وقراءة الرؤوس، والرد بالبيانات المناسبة في طبقة واجهة برمجة التطبيقات Next.js الخاصة بك. + +> **ملاحظة:** إذا كنت تحتاج فقط إلى جلب بيانات من جانب الخادم لتطبيق Next.js الخاص بك (ولا تحتاج إلى مشاركة هذه البيانات خارجيًا)، فقد تكون مكونات الخادم (Server Components) كافية لجلب البيانات مباشرة أثناء العرض - ولا حاجة إلى طبقة واجهة برمجة تطبيقات منفصلة. + +[3. إنشاء واجهة برمجة تطبيقات باستخدام معالجات المسارات (Route Handlers)](#3-creating-an-api-with-route-handlers) +--------------------------------------------------------------------------------- + +### [3.1 إعداد الملف الأساسي](#31-basic-file-setup) + +في موجه التطبيق (`app/`)، أنشئ مجلدًا يمثل مسارك، وداخله ملف `route.ts`. + +على سبيل المثال، لإنشاء نقطة نهاية عند `/api/users`: + +``` +app +└── api + └── users + └── route.ts +``` + +### [3.2 طرق HTTP متعددة في ملف واحد](#32-multiple-http-methods-in-one-file) + +على عكس مسارات واجهة برمجة التطبيقات في موجه الصفحات (التي كان لها تصدير افتراضي واحد)، يمكنك تصدير دوال متعددة تمثل طرق HTTP مختلفة من نفس الملف. + +```ts filename="app/api/users/route.ts" +export async function GET(request: Request) { + // على سبيل المثال، جلب البيانات من قاعدة البيانات هنا + const users = [ + { id: 1, name: 'أليس' }, + { id: 2, name: 'بوب' } + ]; + return new Response(JSON.stringify(users), { + status: 200, + headers: { 'Content-Type': 'application/json' } + }); +} + +export async function POST(request: Request) { + // تحليل جسم الطلب + const body = await request.json(); + const { name } = body; + + // مثلاً، إدراج مستخدم جديد في قاعدة البيانات + const newUser = { id: Date.now(), name }; + + return new Response(JSON.stringify(newUser), { + status: 201, + headers: { 'Content-Type': 'application/json' } + }); +} +``` + +الآن، إرسال طلب GET إلى `/api/users` سيعيد قائمة المستخدمين الخاصة بك، بينما طلب `POST` إلى نفس العنوان URL سيدرج مستخدمًا جديدًا. + +[4. العمل مع واجهات برمجة تطبيقات الويب (Web APIs)](#4-working-with-web-apis) +----------------------------------------------------- + +### [4.1 استخدام Request و Response مباشرة](#41-directly-using-request--response) + +بشكل افتراضي، تتلقى طرق معالج المسار (`GET`، `POST`، إلخ) كائن [Request](https://developer.mozilla.org/docs/Web/API/Request) قياسي، ويجب عليك إرجاع كائن [Response](https://developer.mozilla.org/docs/Web/API/Response) قياسي. + +### [4.2 معاملات الاستعلام (Query parameters)](#42-query-parameters) + +```ts filename="app/api/search/route.ts" +import { NextRequest } from 'next/server'; + +export function GET(request: NextRequest) { + const searchParams = request.nextUrl.searchParams; + const query = searchParams.get('query'); // مثلاً `/api/search?query=مرحبا` + + return new Response( + JSON.stringify({ result: `لقد بحثت عن: ${query}` }), + { + headers: { 'Content-Type': 'application/json' }, + }, + ); +} +``` + +### [4.3 الرؤوس (Headers) وملفات تعريف الارتباط (Cookies)](#43-headers-and-cookies) + +```ts filename="app/api/auth/route.ts" +import { NextRequest } from 'next/server'; +import { cookies, headers } from 'next/headers'; + +export async function GET(request: NextRequest) { + // 1. استخدام أدوات 'next/headers' + const cookieStore = await cookies(); + const token = cookieStore.get('token'); + + const headersList = await headers(); + const referer = headersList.get('referer'); + + // 2. استخدام واجهات برمجة تطبيقات الويب القياسية + const userAgent = request.headers.get('user-agent'); + + return new Response(JSON.stringify({ token, referer, userAgent }), { + headers: { 'Content-Type': 'application/json' }, + }); +} +``` + +يمكن أن تكون الدوال `cookies()` و `headers()` مفيدة إذا كنت تخطط لإعادة استخدام المنطق المشترك عبر كود جانب الخادم الآخر في Next.js. ستلاحظ أن Next.js يوفر أيضًا `NextRequest` و `NextResponse` اللذين يمتدان واجهات برمجة تطبيقات الويب الأساسية. + +[5. المسارات الديناميكية](#5-dynamic-routes) +--------------------------------------- + +لإنشاء مسارات ديناميكية (مثل `/api/users/:id`)، استخدم **مقاطع ديناميكية** في بنية مجلدك: + +``` +app +└── api + └── users + └── [id] + └── route.ts +``` + +يتوافق هذا الملف مع عنوان URL مثل `/api/users/123`، حيث يتم التقاط `123` كمعامل. + +```ts filename="app/api/users/[id]/route.ts" +import { NextRequest } from 'next/server'; + +export async function GET( + request: NextRequest, + { params }: { params: Promise<{ id: string }> }, +) { + const id = (await params).id; + // مثلاً، استعلام قاعدة بيانات عن مستخدم بالمعرف `id` + return new Response(JSON.stringify({ id, name: `المستخدم ${id}` }), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }); +} + +export async function DELETE( + request: NextRequest, + { params }: { params: Promise<{ id: string }> }, +) { + const id = (await params).id; + // مثلاً، حذف مستخدم بالمعرف `id` من قاعدة البيانات + return new Response(null, { status: 204 }); +} +``` + +هنا، يعطيك `params.id` المقطع الديناميكي. + +[6. استخدام Next.js كطبقة وكيل (proxy) أو توجيه](#6-using-nextjs-as-a-proxy-or-forwarding-layer) +-------------------------------------------------------------------------------------------------- + +سيناريو شائع هو **التصرف كوسيط** لخدمة خلفية موجودة. يمكنك مصادقة الطلبات، والتعامل مع التسجيل، أو تحويل البيانات قبل إرسالها إلى خادم بعيد أو خلفية: + +```ts filename="app/api/external/route.ts" +import { NextRequest } from 'next/server'; + +export async function GET(request: NextRequest) { + const response = await fetch('https://example.com/api/data', { + // اختياري: توجيه بعض الرؤوس، إضافة رموز مصادقة، إلخ. + headers: { Authorization: `Bearer ${process.env.API_TOKEN}` }, + }); + + // تحويل أو توجيه الاستجابة + const data = await response.json(); + const transformed = { ...data, source: 'تم تمريره عبر-nextjs' }; + + return new Response(JSON.stringify(transformed), { + headers: { 'Content-Type': 'application/json' }, + }); +} +``` + +الآن يحتاج عملاؤك فقط إلى استدعاء `/api/external`، وسيتعامل Next.js مع الباقي. يُطلق على هذا أحيانًا اسم "الخلفية للواجهة الأمامية" أو BFF. + +[7. بناء منطق "وسيط" مشترك](#7-building-shared-middleware-logic) +----------------------------------------------------------------------------- + +إذا كنت تريد تطبيق نفس المنطق (مثل فحوصات المصادقة، التسجيل) عبر معالجات مسارات متعددة، يمكنك إنشاء دوال قابلة لإعادة الاستخدام تغلف معالجاتك: + +```ts filename="lib/with-auth.ts" +import { NextRequest } from 'next/server'; + +type Handler = (req: NextRequest, context?: any) => Promise; + +export function withAuth(handler: Handler): Handler { + return async (req, context) => { + const token = req.cookies.get('token')?.value; + if (!token) { + return new Response(JSON.stringify({ error: 'غير مصرح' }), { + status: 401, + headers: { 'Content-Type': 'application/json' }, + }); + } + + // إذا تمت المصادقة، استدع المعالج الأصلي + return handler(req, context); + }; +} +``` + +ثم في معالج المسار الخاص بك: + +```ts filename="app/api/secret/route.ts" +import { NextRequest } from 'next/server'; +import { withAuth } from '@/lib/with-auth'; + +async function secretGET(request: NextRequest) { + return new Response(JSON.stringify({ secret: 'هنا توجد تنانين' }), { + headers: { 'Content-Type': 'application/json' }, + }); +} + +export const GET = withAuth(secretGET); +``` + +[8. اعتبارات النشر ووضع "تطبيق الصفحة الواحدة (SPA)"](#8-deployment-and-spa-mode-considerations) +----------------------------------------------------------------------------------------- + +### [8.1 النشر القياسي لـ Node.js](#81-standard-nodejs-deployment) + +يتيح لك نشر خادم Next.js القياسي باستخدام `next start` استخدام ميزات مثل معالجات المسارات (Route Handlers)، ومكونات الخادم (Server Components)، والوسيط (Middleware) والمزيد - مع الاستفادة من المعلومات الديناميكية في وقت الطلب. + +لا يلزم أي تكوين إضافي. راجع [النشر](/docs/app/building-your-application/deploying) لمزيد من التفاصيل. + +### [8.2 تصدير ثابت/وضع تطبيق الصفحة الواحدة (SPA/Static Export)](#82-spastatic-export) + +يدعم Next.js أيضًا إخراج موقعك بالكامل كـ [تطبيق صفحة واحدة ثابت (SPA)](/docs/app/building-your-application/upgrading/single-page-applications). + +يمكنك تمكين هذا عن طريق تعيين: + +```ts filename="next.config.ts" +import type { NextConfig } from 'next'; + +const nextConfig: NextConfig = { + output: 'export', +}; + +export default nextConfig; +``` + +في **وضع التصدير الثابت**، سينشئ Next.js HTML وCSS وJS ثابتًا بحتًا. **لا يمكنك تشغيل كود جانب الخادم** (مثل نقاط نهاية واجهة برمجة التطبيقات). إذا كنت لا تزال بحاجة إلى واجهة برمجة تطبيقات، فسيتعين عليك استضافتها بشكل منفصل (مثل خادم Node.js مستقل). + +> **ملاحظة:** +> +> * يمكن تصدير **معالجات مسارات GET** [بشكل ثابت](/docs/app/building-your-application/deploying/static-exports#route-handlers) إذا لم تعتمد على بيانات طلب ديناميكية. تصبح ملفات ثابتة في مجلد `out` الخاص بك. +> * **جميع ميزات الخادم الأخرى** (الطلبات الديناميكية، إعادة كتابة ملفات تعريف الارتباط، إلخ) **غير** مدعومة في تصدير SPA بحت. + +[9. متى تتخطى إنشاء نقطة نهاية لواجهة برمجة التطبيقات](#9-when-to-skip-creating-an-api-endpoint) +------------------------------------------------------------------------------------------------- + +في بعض الحالات، قد لا تحتاج إلى إنشاء نقطة نهاية لواجهة برمجة التطبيقات منفصلة: + +1. **جلب البيانات لمكونات الخادم (Server Components)**: إذا كنت تجلب البيانات فقط لعرضها في صفحة Next.js الخاصة بك، يمكنك جلبها مباشرة في مكون خادم باستخدام `async/await` دون الحاجة إلى واجهة برمجة تطبيقات منفصلة. +2. **إجراءات الخادم (Server Actions)**: لمعالجة نماذج أو تنفيذ عمليات جانبية، يمكنك استخدام [إجراءات الخادم](/docs/app/building-your-application/data-fetching/server-actions) بدلاً من نقاط نهاية واجهة برمجة التطبيقات التقليدية. +3. **الوظائف الثابتة البسيطة**: إذا كانت الوظيفة لا تتطلب بيانات ديناميكية من الطلب، يمكن تنفيذها كدالة JavaScript عادية في كود العميل. + +[10. جمع كل شيء معًا](#10-putting-it-all-together) +-------------------------------------------------- + +لنقم بإنشاء مثال شامل يجمع بين العديد من المفاهيم التي تعلمناها: + +```ts filename="app/api/todos/[id]/route.ts" +import { NextRequest, NextResponse } from 'next/server'; +import { withAuth } from '@/lib/with-auth'; +import { db } from '@/lib/db'; + +// GET /api/todos/:id +async function getTodo( + request: NextRequest, + { params }: { params: { id: string } } +) { + const todo = await db.todo.findUnique({ + where: { id: params.id }, + }); + + if (!todo) { + return NextResponse.json( + { error: 'Todo not found' }, + { status: 404 } + ); + } + + return NextResponse.json(todo); +} + +// PATCH /api/todos/:id +async function updateTodo( + request: NextRequest, + { params }: { params: { id: string } } +) { + const body = await request.json(); + const updated = await db.todo.update({ + where: { id: params.id }, + data: body, + }); + return NextResponse.json(updated); +} + +// DELETE /api/todos/:id +async function deleteTodo( + request: NextRequest, + { params }: { params: { id: string } } +) { + await db.todo.delete({ + where: { id: params.id }, + }); + return new Response(null, { status: 204 }); +} + +export const GET = withAuth(getTodo); +export const PATCH = withAuth(updateTodo); +export const DELETE = withAuth(deleteTodo); +``` + +يوضح هذا المثال: +- استخدام الوسيط (Middleware) للمصادقة +- التعامل مع طرق HTTP متعددة +- المسارات الديناميكية +- التعامل مع الأخطاء +- الاتصال بقاعدة بيانات + +[الختام](#conclusion) +---------------------- + +يوفر Next.js طريقة قوية لبناء واجهات برمجة التطبيقات جنبًا إلى جنب مع تطبيقات الويب الخاصة بك. من خلال معالجات المسارات (Route Handlers)، يمكنك: + +- إنشاء نقاط نهاية RESTful API +- التصرف كطبقة وسيطة للخدمات الخلفية +- تنفيذ منطق المصادقة المشترك +- التعامل مع الخطافات الويب (Webhooks) والتكاملات + +تذكر أن Next.js يدعم أيضًا طرقًا أخرى لجلب البيانات ومعالجتها مثل مكونات الخادم (Server Components) وإجراءات الخادم (Server Actions). اختر النهج الذي يناسب احتياجاتك المحددة. + +[الأسئلة الشائعة](#frequently-asked-questions) +---------------------------------------------- + +### [ماذا عن إجراءات الخادم (Server Actions)؟](#what-about-server-actions) + +إجراءات الخادم (Server Actions) هي طريقة بديلة لتنفيذ عمليات جانب الخادم في Next.js. إنها مفيدة بشكل خاص لمعالجة نماذج HTML وتنفيذ الطفرات (mutations). بينما تعمل معالجات المسارات (Route Handlers) كنقاط نهاية واجهة برمجة تطبيقات تقليدية، تعمل إجراءات الخادم بشكل أكثر تكاملاً مع مكونات React. + +### [هل يمكنني استخدام TypeScript مع معالجات المسارات (Route Handlers)؟](#can-i-use-typescript-with-route-handlers) + +نعم! تدعم معالجات المسارات (Route Handlers) TypeScript بشكل كامل. يوفر Next.js أنواعًا لـ `NextRequest`، `NextResponse`، وغيرها من الأدوات المساعدة. يمكنك أيضًا تحديد أنواع لأجسام الطلبات والاستجابات الخاصة بك. + +### [ما هي أفضل الممارسات للمصادقة (Authentication)؟](#what-are-the-best-practices-for-authentication) + +تتضمن بعض أفضل الممارسات: +1. استخدم HTTPS دائمًا +2. تخزين الرموز المميزة (tokens) بشكل آمن في ملفات تعريف الارتباط HTTP-only +3. تنفيذ التحقق من الصلاحية (validation) على جانب الخادم دائمًا +4. استخدام وسيط (middleware) للمصادقة المشتركة +5. النظر في استخدام حلول مثل NextAuth.js أو Auth.js للتعامل مع المصادقة المعقدة + +### [8.3 نشر واجهات برمجة التطبيقات (APIs) على Vercel](#83-deploying-apis-on-vercel) + +إذا كنت تقوم بنشر تطبيق Next.js الخاص بك على Vercel، لدينا [دليل حول نشر واجهات برمجة التطبيقات (APIs)](https://vercel.com/guides/hosting-backend-apis). يتضمن ذلك ميزات أخرى من Vercel مثل [الحد من المعدل البرمجي (programmatic rate-limiting)](https://vercel.com/docs/security/vercel-waf/rate-limiting-sdk) من خلال جدار الحماية (Firewall) الخاص بـ Vercel. كما يقدم Vercel أيضًا [وظائف مجدولة (Cron Jobs)](https://vercel.com/docs/cron-jobs/manage-cron-jobs)، والتي غالبًا ما تكون مطلوبة مع منهجيات واجهات برمجة التطبيقات. + +[9\. متى تتخطى إنشاء نقطة نهاية لواجهة برمجة التطبيقات (API endpoint)](#9-when-to-skip-creating-an-api-endpoint) +------------------------------------------------------------------------------------- + +مع **مكونات الخادم في React (React Server Components)** في App Router، يمكنك جلب البيانات مباشرة من الخادم دون الكشف عن نقطة نهاية عامة: + +```tsx filename="app/users/page.tsx" +// (مكون الخادم - Server Component) +export default async function UsersPage() { + // هذا الـ fetch يعمل على الخادم (لا حاجة لكود من جانب العميل هنا) + const res = await fetch('https://api.example.com/users'); + const data = await res.json(); + + return ( +
+

المستخدمون

+
    + {data.map((user: any) => ( +
  • {user.name}
    • + ))} +
+
+ ); +} +``` + +إذا كانت بياناتك تستخدم فقط داخل تطبيق Next.js الخاص بك، فقد لا تحتاج إلى واجهة برمجة تطبيقات عامة على الإطلاق. + +[10\. تجميع كل شيء معًا](#10-putting-it-all-together) +----------------------------------------------------------- + +1. **إنشاء مشروع Next.js جديد**: `npx create-next-app@latest --api`. +2. **إضافة معالجات المسارات (Route Handlers)** داخل مجلد `app/` (مثال: `app/api/users/route.ts`). +3. **تصدير طرق HTTP** (`GET`, `POST`, `PUT`, `DELETE`, إلخ) في نفس الملف. +4. **استخدام واجهات برمجة التطبيقات القياسية للويب (Web Standard APIs)** للتفاعل مع كائن `Request` وإرجاع `Response`. +5. **بناء واجهة برمجة تطبيقات عامة** إذا كنت بحاجة إلى أن تستهلكها عملاء أخرى، أو لوكيل خدمة خلفية. +6. **جلب** مسارات واجهة برمجة التطبيقات الجديدة من العميل (مثال: داخل مكون العميل أو باستخدام `fetch('/api/...')`). +7. أو **تخطي إنشاء واجهة برمجة تطبيقات** تمامًا إذا كان مكون الخادم يمكنه جلب البيانات مباشرة. +8. **إضافة نمط "وسيط مشترك (middleware)"** (مثال: `withAuth()`) للمصادقة أو أي منطق متكرر آخر. +9. **النشر** على بيئة تدعم Node.js لميزات الخادم، أو **تصدير** ثابت إذا كنت بحاجة فقط إلى تطبيق صفحة واحدة ثابت (SPA). + +[الختام](#conclusion) +------------------------- + +استخدام **App Router** و **Route Handlers** في Next.js يمنحك طريقة مرنة وعصرية لبناء واجهات برمجة التطبيقات التي تتبنى **منصة الويب (Web Platform)** مباشرة. يمكنك: + +* **إنشاء واجهة برمجة تطبيقات عامة كاملة** لمشاركتها مع الويب أو الهاتف المحمول أو عملاء طرف ثالث. +* **الوكيل** وتخصيص المكالمات إلى الخدمات الخارجية الموجودة. +* **تنفيذ** طبقة "وسيط (middleware)" قابلة لإعادة الاستخدام للمصادقة أو التسجيل أو أي منطق متكرر. +* **توجيه الطلبات ديناميكيًا** باستخدام هيكل مجلدات القطاع `[id]`. + +[الأسئلة الشائعة](#frequently-asked-questions) +--------------------------------------------------------- + +### [ماذا عن إجراءات الخادم (Server Actions)؟](#what-about-server-actions) + +يمكنك التفكير في [إجراءات الخادم (Server Actions)](/docs/app/building-your-application/data-fetching/server-actions-and-mutations) مثل مسارات واجهة برمجة التطبيقات `POST` المولدة تلقائيًا والتي يمكن استدعاؤها من العميل. + +تم تصميمها لعمليات التغيير، مثل إنشاء أو تحديث أو حذف البيانات. تستدعي إجراء الخادم مثل دالة JavaScript عادية، بدلاً من إجراء `fetch` صريح إلى مسار واجهة برمجة تطبيقات محدد. + +بينما لا يزال هناك طلب شبكة يحدث، لا تحتاج إلى إدارته صراحة. يتم إنشاء مسار URL تلقائيًا و[تشفيره](/docs/app/building-your-application/data-fetching/server-actions-and-mutations#security)، لذا لا يمكنك الوصول يدويًا إلى مسار مثل `/api/users` في المتصفح. + +إذا كنت تخطط لاستخدام إجراءات الخادم _و_ كشف واجهة برمجة تطبيقات عامة، نوصي بنقل المنطق الأساسي إلى [طبقة وصول البيانات (Data Access Layer)](/blog/security-nextjs-server-components-actions) واستدعاء نفس المنطق من كل من إجراء الخادم ومسار واجهة برمجة التطبيقات. + +### [هل يمكنني استخدام TypeScript مع معالجات المسارات (Route Handlers)؟](#can-i-use-typescript-with-route-handlers) + +نعم، يمكنك استخدام TypeScript مع معالجات المسارات. على سبيل المثال، تحديد أنواع `Request` و `Response` في ملف `route` الخاص بك. + +تعلم المزيد عن [TypeScript مع Next.js](/docs/app/api-reference/config/typescript). + +### [ما هي أفضل الممارسات للمصادقة؟](#what-are-the-best-practices-for-authentication) + +تعلم المزيد في [توثيق المصادقة الخاص بنا](/docs/app/building-your-application/authentication). diff --git a/apps/docs/content/ar/blog/composable-caching.mdx b/apps/docs/content/ar/blog/composable-caching.mdx new file mode 100644 index 00000000..8ad1eab9 --- /dev/null +++ b/apps/docs/content/ar/blog/composable-caching.mdx @@ -0,0 +1,202 @@ +--- +source-updated-at: 2025-05-29T18:05:49.000Z +translation-updated-at: 2025-06-02T19:41:53.370Z +title: التخزين المؤقت القابل للتكوين مع Next.js +description: تعرف على تصميم واجهة برمجة التطبيقات (API) ومزايا التوجيه 'use cache' +author: + - name: لي روبنسون + image: /static/team/lee.jpg +date: 2025-01-03T14:00:00.507Z +image: >- + https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/composable-caching/twitter-card.png +--- + +نحن نعمل على نموذج بسيط وقوي للتخزين المؤقت لـ Next.js. في منشور سابق، تحدثنا عن [رحلتنا مع التخزين المؤقت](/blog/our-journey-with-caching) وكيف توصلنا إلى توجيه `'use cache'`. + +سيناقش هذا المنشور تصميم واجهة برمجة التطبيقات (API) ومزايا `'use cache'`. + +[ما هو `'use cache'`؟](#what-is-use-cache) +-------------------------------------------- + +`'use cache'` يجعل تطبيقك أسرع عن طريق تخزين البيانات أو المكونات مؤقتًا عند الحاجة. + +إنه "توجيه" (directive) في JavaScript - عبارة نصية تضيفها في الكود الخاص بك - والتي تشير إلى مترجم Next.js للدخول إلى "حدود" مختلفة. على سبيل المثال، الانتقال من الخادم إلى العميل. + +هذه فكرة مشابهة لتوجيهات React مثل `'use client'` و `'use server'`. التوجيهات هي تعليمات المترجم التي تحدد مكان تشغيل الكود، مما يسمح للإطار بتحسين وتنسيق الأجزاء الفردية لك. + +[كيف يعمل؟](#how-does-it-work) +-------------------------------------- + +لنبدأ بمثال بسيط: + +``` +async function getUser(id) { + 'use cache'; + let res = await fetch(`https://api.vercel.app/user/${id}`); + return res.json(); +} +``` + +خلف الكواليس، يحول Next.js هذا الكود إلى دالة خادم بسبب توجيه `'use cache'`. أثناء الترجمة، يتم العثور على "التبعيات" (dependencies) لإدخال التخزين المؤقت هذه واستخدامها كجزء من مفتاح التخزين المؤقت. + +على سبيل المثال، يصبح `id` جزءًا من مفتاح التخزين المؤقت. إذا استدعينا `getUser(1)` عدة مرات، فإننا نعيد الإخراج المخزن مؤقتًا من دالة الخادم. تغيير هذه القيمة سينشئ إدخالًا جديدًا في التخزين المؤقت. + +لنلق نظرة على مثال باستخدام الدالة المخزنة مؤقتًا في مكون خادم مع [إغلاق](https://v0.dev/chat/5kD47RIecQK?b=b_rCP4CvfbFFW). + +``` +function Profile({ id }) { + async function getNotifications(index, limit) { + 'use cache'; + return await db + .select() + .from(notifications) + .limit(limit) + .offset(index) + .where(eq(notifications.userId, id)); + } + + return ; +} +``` + +هذا المثال أكثر صعوبة. هل يمكنك تحديد جميع التبعيات التي يجب أن تكون جزءًا من مفتاح التخزين المؤقت؟ + +الوسائط `index` و `limit` منطقية - إذا تغيرت هذه القيم، نختار شريحة مختلفة من الإشعارات. ولكن ماذا عن معرف المستخدم `id`؟ قيمته تأتي من المكون الأصلي. + +يمكن للمترجم فهم أن `getNotifications` يعتمد أيضًا على `id`، ويتم تضمين قيمته تلقائيًا في مفتاح التخزين المؤقت. هذا يمنع فئة كاملة من مشاكل التخزين المؤقت الناتجة عن تبعيات غير صحيحة أو مفقودة في مفتاح التخزين المؤقت. + +[لماذا لا نستخدم دالة تخزين مؤقت؟](#why-not-use-a-cache-function) +-------------------------------------------------------------- + +لنراجع المثال الأخير. هل يمكننا بدلاً من ذلك استخدام دالة `cache()` بدلاً من التوجيه؟ + +``` +function Profile({ id }) { + async function getNotifications(index, limit) { + return await cache(async () => { + return await db + .select() + .from(notifications) + .limit(limit) + .offset(index) + // خطأ! أين ندرج id في مفتاح التخزين المؤقت؟ + .where(eq(notifications.userId, id)); + }); + } + + return ; +} +``` + +لن تتمكن دالة `cache()` من النظر داخل الإغلاق ورؤية أن قيمة `id` يجب أن تكون جزءًا من مفتاح التخزين المؤقت. ستحتاج إلى تحديد يدويًا أن `id` جزء من مفتاحك. إذا نسيت القيام بذلك، أو فعلت ذلك بشكل غير صحيح، فإنك تخاطر بتصادم التخزين المؤقت أو بيانات قديمة. + +يمكن للإغلاقات التقاط جميع أنواع المتغيرات المحلية. قد تؤدي الطريقة الساذجة إلى تضمين (أو حذف) متغيرات لم تقصدها عن طريق الخطأ. هذا يمكن أن يؤدي إلى تخزين بيانات خاطئة مؤقتًا، أو قد يعرضك لخطر تسميم التخزين المؤقت إذا تسربت معلومات حساسة إلى مفتاح التخزين المؤقت. + +يمنح `'use cache'` المترجم سياقًا كافيًا للتعامل مع الإغلاقات بأمان وإنشاء مفاتيح التخزين المؤقت بشكل صحيح. الحل الذي يعمل في وقت التشغيل فقط، مثل `cache()`، سيتطلب منك القيام بكل شيء يدويًا - ومن السهل ارتكاب الأخطاء. في المقابل، يمكن تحليل التوجيه بشكل ثابت للتعامل مع جميع تبعياتك بشكل موثوق تحت الغطاء. + +[كيف يتم التعامل مع قيم الإدخال غير القابلة للتسلسل؟](#how-are-non-serialized-input-values-handled) +-------------------------------------------------------------------------------------------- + +لدينا نوعان مختلفان من قيم الإدخال للتخزين المؤقت: + +* **قابلة للتسلسل (Serializable)**: هنا، "قابلة للتسلسل" تعني أنه يمكن تحويل الإدخال إلى تنسيق مستند إلى سلسلة ومستقر _بدون_ فقدان المعنى. بينما يفكر الكثيرون أولاً في `JSON.stringify`، فإننا نستخدم في الواقع تسلسل React (على سبيل المثال، عبر مكونات الخادم) للتعامل مع نطاق أوسع من المدخلات - بما في ذلك الوعود، وهياكل البيانات الدائرية، والكائنات المعقدة الأخرى. هذا يتجاوز ما يمكن لـ JSON العادي القيام به. +* **غير قابلة للتسلسل (Non-serializable)**: هذه المدخلات ليست جزءًا من مفتاح التخزين المؤقت. عندما نحاول تخزين هذه القيم مؤقتًا، نعيد "مرجع" الخادم. ثم يستخدم Next.js هذا المرجع لاستعادة القيمة الأصلية في وقت التشغيل. + +لنفترض أننا تذكرنا تضمين `id` في مفتاح التخزين المؤقت: + +``` +await cache(async () => { + return await db + .select() + .from(notifications) + .limit(limit) + .offset(index) + .where(eq(notifications.userId, id)); +}, [id, index, limit]); +``` + +هذا يعمل إذا كانت قيم الإدخال قابلة للتسلسل. ولكن إذا كان `id` عنصر React أو قيمة أكثر تعقيدًا، فسيتعين علينا تسلسل مفاتيح الإدخال يدويًا. ضع في اعتبارك مكون خادم يحصل على المستخدم الحالي بناءً على خاصية `id`: + +``` +async function Profile({ id, children }) { + 'use cache'; + const user = await getUser(id); + + return ( + <> +

{user.name}

+ {/* تغيير children لا يكسر التخزين المؤقت... لماذا؟ */} + {children} + + ); +} +``` + +لنتابع كيف يعمل هذا: + +1. أثناء الترجمة، يرى Next.js توجيه `'use cache'` ويحول الكود لإنشاء دالة خادم خاصة تدعم التخزين المؤقت. لا يحدث التخزين المؤقت أثناء الترجمة، ولكن Next.js يقوم بإعداد الآلية اللازمة للتخزين المؤقت في وقت التشغيل. +2. عندما يستدعي الكود الخاص بك "دالة التخزين المؤقت"، يقوم Next.js بتسلسل وسائط الدالة. أي شيء غير قابل للتسلسل مباشرة، مثل JSX، يتم استبداله بـ "مرجع" كعنصر نائب. +3. يتحقق Next.js مما إذا كانت هناك نتيجة مخزنة مؤقتًا لوسائط التسلسل المحددة. إذا لم يتم العثور على نتيجة، تحسب الدالة القيمة الجديدة للتخزين المؤقت. +4. بعد انتهاء الدالة، يتم تسلسل قيمة الإرجاع. يتم تحويل الأجزاء غير القابلة للتسلسل من قيمة الإرجاع إلى مراجع مرة أخرى. +5. يقوم الكود الذي استدعى دالة التخزين المؤقت بإلغاء تسلسل الإخراج وتقييم المراجع. هذا يسمح لـ Next.js بتبديل المراجع بقيمها أو كائناتها الأصلية، مما يعني أن المدخلات غير القابلة للتسلسل مثل `children` يمكنها الاحتفاظ بقيمها الأصلية غير المخزنة مؤقتًا. + +هذا يعني أنه يمكننا تخزين مكون `` فقط مؤقتًا وليس الأطفال. في عمليات التقديم اللاحقة، لا يتم استدعاء `getUser()` مرة أخرى. قد تكون قيمة `children` ديناميكية أو عنصرًا مخزنًا مؤقتًا بشكل منفصل بعمر تخزين مؤقت مختلف. هذا هو التخزين المؤقت القابل للتكوين. + +[يبدو هذا مألوفًا...](#this-seems-familiar) +-------------------------------------------- + +إذا كنت تفكر "هذا يشبه نفس نموذج تكوين الخادم والعميل" - فأنت على حق تمامًا. يُطلق على هذا أحيانًا اسم نمط "الدونات": + +* الجزء **الخارجي** من الدونات هو مكون خادم يتعامل مع جلب البيانات أو المنطق الثقيل. +* **الثقب** في المنتصف هو مكون فرعي قد يكون به بعض التفاعل + +```tsx filename="app/page.tsx" +export default function Page() { + return ( + + {/* إنشاء ثقب إلى العميل */} + + + ); +} +``` + +`'use cache'` هو نفسه. الدونات هي القيمة المخزنة مؤقتًا للمكون الخارجي والثقب هو المراجع التي يتم ملؤها في وقت التشغيل. هذا هو السبب في أن تغيير `children` لا يبطل إخراج التخزين المؤقت بالكامل. الأطفال هم مجرد بعض المراجع التي يتم ملؤها لاحقًا. + +[ماذا عن الوسم والإبطال؟](#what-about-tagging-and-invalidation) +---------------------------------------------------------------------------- + +يمكنك تحديد عمر التخزين المؤقت باستخدام [ملفات تعريف](/docs/app/api-reference/functions/cacheLife) مختلفة. نضمن مجموعة من الملفات الافتراضية، ولكن يمكنك تحديد قيم مخصصة إذا رغبت في ذلك. + +``` +async function getUser(id) { + 'use cache'; + cacheLife('hours'); + let res = await fetch(`https://api.vercel.app/user/${id}`); + return res.json(); +} +``` + +لبطل إدخال تخزين مؤقت معين، يمكنك [وسم التخزين المؤقت](/docs/app/api-reference/functions/cacheTag) ثم استدعاء `revalidateTag()`. نمط قوي واحد هو أنه يمكنك وسم التخزين المؤقت _بعد_ جلب بياناتك (على سبيل المثال من نظام إدارة المحتوى): + +``` +async function getPost(postId) { + 'use cache'; + let res = await fetch(`https://api.vercel.app/blog/${postId}`); + let data = await res.json(); + cacheTag(postId, data.authorId); + return data; +} +``` + +[بسيط وقوي](#simple-and-powerful) +------------------------------------------- + +هدفنا مع `'use cache'` هو جعل كتابة منطق التخزين المؤقت بسيطًا _وقويًا_. + +* **بسيط:** يمكنك إنشاء إدخالات تخزين مؤقت مع تفكير محلي. لا داعي للقلق بشأن الآثار الجانبية العالمية، مثل مفاتيح التخزين المؤقت المنسية أو التغييرات غير المقصودة في أجزاء أخرى من قاعدة الكود الخاصة بك. +* **قوي:** يمكنك تخزين أكثر من مجرد كود قابل للتحليل الثابت. على سبيل المثال، القيم التي قد تتغير في وقت التشغيل، ولكنك لا تزال ترغب في تخزين نتيجة الإخراج مؤقتًا بعد تقييمها. + +`'use cache` لا يزال **تجريبيًا** داخل Next.js. نود الحصول على ملاحظاتك المبكرة أثناء اختباره. + +[تعلم المزيد في الوثائق](/docs/app/api-reference/directives/use-cache). \ No newline at end of file diff --git a/apps/docs/content/ar/blog/create-next-app.mdx b/apps/docs/content/ar/blog/create-next-app.mdx new file mode 100644 index 00000000..a34e9df7 --- /dev/null +++ b/apps/docs/content/ar/blog/create-next-app.mdx @@ -0,0 +1,38 @@ +--- +source-updated-at: 2025-05-29T18:05:49.000Z +translation-updated-at: 2025-06-02T19:40:12.580Z +title: تقديم أداة Create Next App +description: >- + يسعدنا اليوم تقديم الأداة الجديدة Create Next App. تقوم أداة Create Next App بإعداد تطبيق React حديث يعمل بواسطة Next.js بأمر واحد. +author: + - name: Joe Haddad + image: /static/team/timer.jpg + - name: Tim Neutkens + image: /static/team/tim.jpg +date: 2019-10-09T15:02:30.543Z +image: >- + https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/create-next-app/twitter-card.png +--- + +يسعدنا اليوم تقديم الأداة الجديدة Create Next App. + +تقوم أداة Create Next App بإعداد تطبيق React حديث يعمل بواسطة Next.js بأمر واحد. + +للبدء، كل ما عليك فعله هو تنفيذ: + +```bash filename="Terminal" +npx create-next-app +``` + +تم إعادة بناء Create Next App من الصفر لتقديم أفضل تجربة ممكنة للمطورين: + +* **تجربة تفاعلية**: تشغيل `npx create-next-app` (بدون وسائط) سيطلق الآن تجربة تفاعلية ترشدك خلال عملية إعداد المشروع. +* **بدون تبعيات**: أصبحت عملية تهيئة المشروع سريعة جدًا تستغرق **ثانية واحدة فقط**. تحتوي Create Next App على صفر تبعيات وتثبت في **604 كيلوبايت فقط**. قبل التحسينات، كانت النسخة السابقة تبلغ **5.38 ميجابايت**. وهذا يعني تخفيضًا بأكثر من **4.7 ميجابايت**! +* **دعم العمل دون اتصال**: ستكتشف Create Next App تلقائيًا إذا كنت غير متصل بالإنترنت وستقوم بتهيئة مشروعك باستخدام ذاكرة التخزين المؤقت المحلية للحزم. +* **قالب مشروع جديد افتراضي**: تستخدم Create Next App قالب مشروع جديد مصمم لتطبيقات Next.js الحديثة. نظرًا لأن Create Next App تتم صيانتها الآن جنبًا إلى جنب مع Next.js نفسها، سيكون هذا القالب دائمًا محدثًا بأحدث إصدار من Next.js! +* **دعم الأمثلة**: يمكن لـ Create Next App تهيئة تطبيقك باستخدام مثال من [مجموعة أمثلة Next.js](https://github.com/vercel/next.js/tree/canary/examples) (مثال: `npx create-next-app --example api-routes`). +* **تم اختباره**: الحزمة جزء من مستودع Next.js الأحادي وتم اختبارها باستخدام نفس مجموعة اختبارات التكامل مثل Next.js نفسها، مما يضمن عملها كما هو متوقع مع كل إصدار. + +كانت Create Next App سابقًا مشروعًا [محفوظًا من قبل المجتمع](https://open.segment.com/create-next-app/)، لكننا شعرنا أنه من المهم تحسين الانطباع الأول عن Next.js. خاصةً وأننا نوصي بها في [مجموعة أمثلة Next.js](https://github.com/vercel/next.js/tree/canary/examples). + +لقد تعاوننا مع [Segment](https://segment.com/) لنقل ملكية الحزمة، ونحن ممتنون جدًا لرعايتهم السابقة، خاصة من قبل [Fouad Matin](https://twitter.com/fouadmatin). \ No newline at end of file diff --git a/apps/docs/content/ar/blog/incremental-adoption.mdx b/apps/docs/content/ar/blog/incremental-adoption.mdx new file mode 100644 index 00000000..bae97e61 --- /dev/null +++ b/apps/docs/content/ar/blog/incremental-adoption.mdx @@ -0,0 +1,109 @@ +--- +source-updated-at: 2025-05-29T18:05:49.000Z +translation-updated-at: 2025-06-02T19:41:06.819Z +title: تبني Next.js تدريجياً +description: >- + تعلم استراتيجيات مختلفة لتبني Next.js تدريجياً في سير عمل التطوير الخاص بك. +author: + - name: لي روبنسون + image: /static/team/lee.jpg +date: 2020-11-18T14:00:00.507Z +image: >- + https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/incremental-adoption/twitter-card.png +--- + +تم تصميم [Next.js](https://nextjs.org/) ليكون قابلاً للتبني التدريجي. مع Next.js، يمكنك الاستمرار في استخدام الكود الحالي الخاص بك وإضافة ما تحتاجه من React (سواء كان قليلاً أو كثيراً). من خلال البدء على نطاق صغير وإضافة المزيد من الصفحات تدريجياً، يمكنك تجنب تعطيل العمل على الميزات عن طريق تفادي إعادة الكتابة الكاملة. + +تحتاج العديد من الشركات إلى تحديث بنيتها التقنية لتقليل التكاليف، وزيادة إنتاجية المطورين، وتقديم أفضل تجربة لعملائها. لقد حسّن التطوير القائم على المكونات (Component-driven development) بشكل كبير سرعة النشر وإمكانية إعادة استخدام أكواد القواعد البرمجية الحديثة. + +ومع أكثر من [8 ملايين تنزيل/شهر](https://www.npmtrends.com/react)، تُعتبر React الخيار الرائد للمطورين في التطوير القائم على المكونات. Next.js، إطار عمل React للإنتاج، يتيح لك تبني React تدريجياً. + +[الدافع](#motivation) +------------------------- + +في عالم يزداد اعتماداً على الأجهزة المحمولة، أصبح تحسين وتتبع [مؤشرات الويب الأساسية (Core Web Vitals)](/analytics) أمراً بالغ الأهمية للنجاح. من المحتمل أن يكون عملاؤك موزعين في جميع أنحاء العالم بسرعات إنترنت متفاوتة. كل ثانية (أو جزء من الثانية) إضافية يقضيها المستخدم في انتظار تحميل الصفحة أو إكمال إجراء ما قد تكون الفارق بين تحقيق عملية بيع أو انطباع أو تحويل. + +إذا كنت تقوم بتحديث بنيتك التقنية، فقد تواجه تحديات مثل: + +* يحتوي تطبيقك على أكواد قديمة تعود لسنوات يصعب فهمها وقد تستغرق سنوات (وملايين الدولارات) لإعادة كتابتها بالكامل. +* تزداد أوقات تحميل الصفحات مع زيادة حجم وتعقيد التطبيق. أصبحت صفحات التسويق البسيطة بطيئة مثل أكثر الصفحات تعقيداً. +* تحاول توسيع فريق التطوير الخاص بك، ولكنك تواجه صعوبات في إضافة المزيد من المطورين إلى قاعدة الأكواد الحالية. +* لديك عمليات قديمة للتكامل المستمر والنشر (CI/CD) وعمليات DevOps، مما يقلل من إنتاجية المطورين ويجعل من الصعب طرح تغييرات جديدة بشكل آمن وموثوق. +* تطبيقك غير متجاوب مع الأجهزة المحمولة ومن المستحيل تحديث التنسيق العام للصفحة دون كسر أجزاء أخرى من التطبيق. + +أنت تعلم أنك بحاجة إلى فعل شيء ما، ولكن قد يكون من الصعب فهم [من أين تبدأ](https://www.psychologytoday.com/us/blog/mindfully-present-fully-alive/201804/the-only-way-eat-elephant). من خلال تبني Next.js تدريجياً، يمكنك البدء في حل المشكلات المذكورة أعلاه وتحويل تطبيقك. دعونا نناقش بعض الاستراتيجيات المختلفة لتبني Next.js في البنية التقنية الحالية الخاصة بك. + +[الاستراتيجيات](#strategies) +------------------------- + +### [مسار فرعي (Subpath)](#subpath) + +الاستراتيجية الأولى هي تكوين خادمك أو الوكيل (proxy) بحيث يشير كل شيء تحت مسار فرعي معين إلى تطبيق Next.js. على سبيل المثال، قد يكون موقعك الحالي على `example.com`، ويمكنك تكوين الوكيل بحيث يقدم `example.com/store` متجراً إلكترونياً مبنيًا باستخدام Next.js. + +باستخدام [`basePath`](/docs/pages/api-reference/next-config-js/basePath)، يمكنك تكوين أصول وروابط تطبيق Next.js الخاص بك للعمل تلقائياً مع المسار الفرعي الجديد `/store`. نظراً لأن كل صفحة في Next.js هي [مسار مستقل (standalone route)](/docs/pages/building-your-application/routing)، فإن صفحات مثل `pages/products.js` ستوجه إلى `example.com/store/products` في تطبيقك. + +```js filename="next.config.js" +module.exports = { + basePath: '/store', +}; +``` + +لمعرفة المزيد عن `basePath`، راجع [الوثائق](/docs/pages/api-reference/next-config-js/basePath). + +(**ملاحظة:** تم تقديم هذه الميزة في Next.js 9.5 وما فوق. إذا كنت تستخدم إصدارات أقدم من Next.js، يرجى الترقية قبل تجربتها.) + +### [إعادة الكتابة (Rewrites)](#rewrites) + +الاستراتيجية الثانية هي إنشاء تطبيق Next.js جديد يشير إلى عنوان URL الجذر لمجالك. ثم يمكنك استخدام [`rewrites`](/docs/pages/api-reference/next-config-js/rewrites) داخل `next.config.js` لجعل بعض المسارات الفرعية يتم توجيهها إلى تطبيقك الحالي. + +على سبيل المثال، لنفترض أنك أنشأت تطبيق Next.js ليتم تقديمه من `example.com` مع `next.config.js` التالي. الآن، سيتم التعامل مع الطلبات للصفحات التي أضفتها إلى تطبيق Next.js هذا (مثل `/about` إذا أضفت `pages/about.js`) بواسطة Next.js، وسيتم توجيه طلبات أي مسار آخر (مثل `/dashboard`) إلى `proxy.example.com`. + +```js filename="next.config.js" +module.exports = { + async rewrites() { + return [ + // نحتاج إلى تعريف إعادة كتابة لا تفعل شيئاً لتفعيل التحقق + // من جميع الصفحات/الملفات الثابتة قبل محاولة التوجيه + { + source: '/:path*', + destination: '/:path*', + }, + { + source: '/:path*', + destination: `https://proxy.example.com/:path*`, + }, + ]; + }, +}; +``` + +لمعرفة المزيد عن إعادة الكتابة، راجع [الوثائق](/docs/pages/api-reference/next-config-js/rewrites). + +### [واجهات أمامية مصغرة مع مستودعات أحادية ونطاقات فرعية (Micro-Frontends with Monorepos and Subdomains)](#micro-frontends-with-monorepos-and-subdomains) + +تجعل Next.js و[Vercel](https://vercel.com) من السهل تبني [الواجهات الأمامية المصغرة (micro-frontends)](https://martinfowler.com/articles/micro-frontends.html) والنشر كمستودع أحادي (Monorepo). يتيح لك ذلك استخدام [النطاقات الفرعية (subdomains)](https://en.wikipedia.org/wiki/Subdomain) لتبني التطبيقات الجديدة تدريجياً. بعض فوائد الواجهات الأمامية المصغرة: + +* قواعد أكواد أصغر وأكثر تماسكاً وسهولة في الصيانة. +* منظمات أكثر قابلية للتوسع مع فرق مستقلة ومنفصلة. +* القدرة على ترقية أو تحديث أو حتى إعادة كتابة أجزاء من الواجهة الأمامية بطريقة أكثر تدريجية. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/incremental-adoption/light-arch.png) + +> بنية مستودع أحادي يتم نشره على Vercel. + +بمجرد إعداد المستودع الأحادي الخاص بك، ادفع التغييرات إلى مستودع Git الخاص بك كالمعتاد وسترى أن الالتزامات يتم نشرها إلى مشاريع Vercel التي قمت بربطها. قل وداعاً لعمليات التكامل المستمر والنشر القديمة. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/incremental-adoption/dark-comment.png) + +> مثال على عناوين URL للنشر المقدمة من تكامل Git. + +[الختام](#conclusion) +------------------------- + +تم تصميم Next.js ليتم تبنيه تدريجياً في البنية التقنية الحالية الخاصة بك. تجعل منصة Vercel هذه التجربة تعاونية مع معاينات النشر لكل تغيير في الكود، من خلال التكامل السلس مع GitHub وGitLab وBitbucket. + +* معاينة التغييرات على الفور محلياً باستخدام [التحديث السريع (Fast Refresh)](/docs/architecture/fast-refresh)، مما يزيد من إنتاجية المطورين. +* ادفع التغييرات لإنشاء [معاينة الفرع (Branch Preview)](https://vercel.com/github)، مُحسّنة للتعاون مع أصحاب المصلحة. +* انشر في الإنتاج باستخدام [Vercel](https://vercel.com) عن طريق دمج طلب السحب (PR). لا حاجة لعمليات DevOps معقدة. + +لمعرفة المزيد، اقرأ عن [المسارات الفرعية (subpaths)](/docs/pages/api-reference/next-config-js/basePath) و[إعادة الكتابة (rewrites)](/docs/pages/api-reference/next-config-js/rewrites) أو [انشر مثالاً مع واجهات أمامية مصغرة](https://vercel.com/import/project?template=https://github.com/vercel/next.js/tree/canary/examples/with-zones). \ No newline at end of file diff --git a/apps/docs/content/ar/blog/june-2023-update.mdx b/apps/docs/content/ar/blog/june-2023-update.mdx new file mode 100644 index 00000000..11ae42e3 --- /dev/null +++ b/apps/docs/content/ar/blog/june-2023-update.mdx @@ -0,0 +1,147 @@ +--- +source-updated-at: 2025-05-29T18:05:49.000Z +translation-updated-at: 2025-06-02T19:41:58.432Z +title: تحديث موجه التطبيق (App Router) في Next.js +description: >- + يركز فريق Next.js على الأداء والاستقرار وتجربة المطور خلال الأشهر القادمة. +author: + - name: ديلبا دي أوليفيرا + image: /static/team/delba.jpg + - name: لي روبنسون + image: /static/team/lee.jpg +date: 2023-06-22T14:00:00.507Z +image: >- + https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/june-2023-update/twitter-card.png +--- + +يمثل موجه التطبيق (App Router) أساسًا جديدًا لمستقبل Next.js، لكننا ندرك أن هناك فرصًا لتحسين التجربة. نود تقديم تحديث حول أولوياتنا الحالية. + +لإصدارات Next.js القادمة، نركز على المجالات التالية: + +* **تحسين الأداء** +* **تحسين الاستقرار** +* **تحسين تعليم المطورين** + +[موجه التطبيق (App Router)](#the-app-router) +--------------------------------- + +أولاً، من المفيد تقديم بعض السياق حول كيفية تصميم موجه التطبيق. + +### [التوسع خارج موجه الصفحات (Pages Router) من خلال المحاذاة مع React](#growing-beyond-the-pages-router-by-aligning-with-react) + +مع زيادة الاعتماد وتطبيقات أكبر حجمًا تُبنى باستخدام Next.js، تلقينا ملاحظات من المجتمع وحددنا مجالات بدأنا فيها بالوصول إلى حدود موجه الصفحات (Pages Router). + +الأهم من ذلك، أن موجه الصفحات (Pages Router) في Next.js لم يُصمم للبث (streaming)، وهو حجر أساس في React الحديث، مما يساعدنا في معالجة القيود التي واجهناها وتحقيق رؤيتنا طويلة المدى لـ Next.js. + +تتطلب إنشاء واجهات برمجة تطبيقات (APIs) إطار عمل صديقة للبث لجلب البيانات وتحميل الأصول وبيانات الصفحة، بالإضافة إلى الاستفادة من البدائيات الأحدث في React، تغييرات كبيرة في البنية الأساسية لـ Next.js. + +استغللنا الفرصة للبناء على [أحدث ميزات React المتزامنة](https://react.dev/blog/2023/05/03/react-canaries)، مثل مكونات الخادم (Server Components) وSuspense وغيرها، والتي تم [تصميمها لبنى البث](https://github.com/reactwg/react-18/discussions/37). + +### [التبني التدريجي غير قابل للتفاوض](#incremental-adoption-is-non-negotiable) + +لم نرغب في أن يضطر مجتمعنا إلى إعادة بناء تطبيقاتهم بالكامل من الصفر للترقية إلى أحدث إصدار من Next.js. نؤمن أن التبني التدريجي هو أفضل استراتيجية لتطوير التطبيقات بمرور الوقت. + +* **هجرة تدريجية لكل مسار**: دون إعادة كتابة كاملة لتطبيقك، يمكنك نقل مسار واحد من تطبيقك إلى موجه التطبيق (App Router) والبدء في الاستفادة من الميزات الجديدة بوتيرتك الخاصة. راجع [دليل التبني التدريجي](/docs/app/building-your-application/upgrading/app-router-migration) أو [شاهد البرنامج التعليمي](https://www.youtube.com/watch?v=YQMSietiFm0). +* **التراجع بسهولة**: إذا لم تكن راضيًا عن أداء أو تجربة المطور لموجه التطبيق، يمكنك بسهولة العودة إلى موجه الصفحات (Pages Router) لهذا المسار المحدد. + +نستكشف فرصًا إضافية لجعل التبني التدريجي أسهل. + +### [الطريق إلى الاستقرار](#road-to-stability) + +بدأنا بناء موجه التطبيق (App Router) في Next.js منذ أكثر من عام وكنا نطلق باستمرار ميزات وتحسينات جديدة منذ ذلك الحين. + +* **الإعلان الأولي**: في مايو من ذلك العام، [أصدرنا طلب تعليقات (RFC)](/blog/layouts-rfc) لتوضيح خططنا لجعل التوجيه والتخطيطات أكثر مرونة. +* **الإصدار التجريبي المبكر**: في Next.js 13، أصدرنا الإصدار الأول من موجه التطبيق، مما سمح للمجتمع بتجربته وتقديم ملاحظات مبكرة. +* **واجهة برمجة التطبيقات (API) المستقرة**: استجابة للملاحظات، ركزنا جهودنا على إنهاء واجهة برمجة التطبيقات الأساسية. في الإصدار 13.4، صنفنا واجهة برمجة التطبيقات الأساسية لموجه التطبيق على أنها مستقرة وجاهزة للتبني الأوسع. + +[تركيزنا الحالي](#our-current-focus) +--------------------------------------- + +أشار الإعلان عن الاستقرار إلى المجتمع أن واجهة برمجة التطبيقات الأساسية قد استقرت ولن تخضع لتغييرات كبيرة تتطلب إعادة كتابة. + +منذ ذلك الحين، تلقينا الكثير من الملاحظات القيمة وكشف التبني المتزايد عن أخطاء وفرص لمزيد من التحسين. + +نريد أن تعلم أننا **لسنا راضين بعد** عن تجربة استخدام موجه التطبيق وهو أولويتنا الرئيسية للمضي قدمًا. لذا، لنتحدث عن العمل الذي نقوم به لتحسين هذه التجربة. + +### [تحسين الأداء](#improving-performance) + +خلال الأشهر القادمة، نركز على ثلاثة جوانب من الأداء: سرعة التكرار المحلي، أوقات بناء الإنتاج، وأداء الخادم بدون خادم (serverless). + +#### [أداء التطوير المحلي](#local-development-performance) + +مع نضوج Next.js، ونمو حجم التطبيقات المبنية بها، كنا نستبدل تدريجياً أجزاء من بنيتها الأساسية بأدوات أسرع وأكثر قابلية للتوسع. + +* **تقدم الهجرة**: بدأنا باستبدال Babel _(التجميع)_ وTerser _(التصغير)_ بـ [SWC](/docs/architecture/nextjs-compiler). ساعد هذا في تحسين سرعات التكرار المحلي وأوقات بناء الإنتاج. + +* **استثمار طويل المدى**: الحفاظ على أداء تحديث سريع (Fast Refresh) رائع بغض النظر عن حجم التطبيقات يعني جعل Next.js تعمل بشكل تدريجي قدر الإمكان أثناء التطوير المحلي، عن طريق تجميع وتجميع التعليمات البرمجية عند الحاجة فقط. + + لهذا السبب نعمل حاليًا على استبدال webpack _(التجميع)_ بـ [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack)، الذي يُبنى على محرك حساب تدريجي منخفض المستوى يمكّن التخزين المؤقت حتى مستوى الوظائف الفردية. + + ستشهد تطبيقات Next.js التي تنتقل إلى Turbopack تحسينات مستمرة في سرعة التحديث السريع حتى مع زيادة حجمها. + + في الأشهر القليلة الماضية، ركز فريق Turbo على تحسين أداء Turbopack والدعم لجميع ميزات Next.js وواجهات برمجة تطبيقات موجه التطبيق. + + يتوفر Turbopack حاليًا [في النسخة التجريبية](/docs/architecture/turbopack) (`next dev --turbo`). + +* **تحسين البنية الحالية**: بالإضافة إلى الاستثمار في المستقبل، نواصل إجراء تحسينات الأداء على بنية webpack الحالية. + + بالنسبة لبعض تطبيقات Next.js، خاصة تلك التي تعيد تحميل آلاف الوحدات، رأينا تقارير عن عدم استقرار في التطوير المحلي والتحديث السريع. نعمل على تحسين الأداء والموثوقية هنا. على سبيل المثال، أضفنا مؤخرًا إعدادات مُهيأة مسبقًا (`modularizeImports`) للتعامل مع [مكتبات الأيقونات الكبيرة](https://github.com/vercel/next.js/pull/50900) التي قد تجبر آلاف الوحدات على إعادة التحميل في كل طلب عن طريق الخطأ. + + +#### [أداء وقت البناء](#build-time-performance) + +نعمل أيضًا على بناء إنتاج باستخدام Turbopack (`next build --turbo`) و[بدأنا في إدراج](https://github.com/vercel/next.js/pull/51546) الأجزاء الأولى من هذا العمل. توقع المزيد من التحديثات حول هذا في الإصدارات القادمة. + +#### [أداء الإنتاج](#production-performance) + +أخيرًا، على Vercel، نعمل على تحسين أداء واستخدام الذاكرة لوظائف Vercel [المحددة من خلال كود تطبيق Next.js](https://vercel.com/blog/framework-defined-infrastructure)، مع ضمان أقل وقت بدء بارد مع الاحتفاظ بمزايا بنية الخادم بدون خادم القابلة للتوسع. أدى هذا العمل إلى [قدرات تتبع جديدة](/docs/app/building-your-application/optimizing/open-telemetry) (تجريبية) في Next.js واستكشافات مبكرة لأدوات المطور من جانب الخادم. + +[تحسين الاستقرار](#improving-stability) +------------------------------------------- + +كان موجه الصفحات (Pages Router) موجودًا منذ ست سنوات الآن. يعني إصدار موجه التطبيق (App Router) تقديم واجهات برمجة تطبيقات جديدة لا تزال حديثة، مع ستة أشهر فقط من الاستخدام. قطعنا شوطًا كبيرًا في وقت قصير، لكن لا تزال هناك فرص للتحسن مع تعلم المزيد من مجتمعنا وكيفية استخدامهم له. + +نقدر استعداد المجتمع لتبني موجه التطبيق بحماس وتقديم الملاحظات. كان هناك عدد من تقارير الأخطاء التي نتحقق منها ونشكركم على الأمثلة المصغرة التي أنشأتموها للمساعدة في عزل المشكلات والتحقق من الإصلاحات. + +منذ الإصدار 13.4، أصلحنا بالفعل عددًا من الأخطاء عالية التأثير حول الاستقرار المتوفرة في أحدث إصدار تصحيح (`13.4.7`). سنواصل التركيز على الأداء والاستقرار بكثافة عالية. + +[تحسين تعليم المطورين](#improving-developer-education) +--------------------------------------------------------------- + +بينما نؤمن بأن الميزات الجديدة لموجه التطبيق وReact الحديثة قوية، إلا أنها تتطلب أيضًا تعليمًا وثائقًا إضافية لمساعدة في تعليم هذه المفاهيم الجديدة. + +### [ميزات Next.js](#nextjs-features) + +كنا نعمل خلال العام الماضي على إعادة كتابة وثائق Next.js من الصفر. هذا العمل متاح الآن على [nextjs.org/docs](/docs). نود تسليط الضوء على بعض [الأجزاء المهمة](https://twitter.com/delba_oliveira/status/1664323492077256704): + +* **تبديل بين الصفحات والتطبيق**: يمكنك التبديل بين تعلم وثائق موجه الصفحات أو موجه التطبيق باستخدام الزر على الجانب الأيسر من الوثائق. علاوة على ذلك، يمكنك تصفية نتائج البحث بناءً على اختيارك للموجه. +* **محتوى محسن وهيكل معلومات**: تم تحديث كل صفحة تقريبًا من وثائق موجه التطبيق، بما في ذلك هيكل أكثر وضوحًا وتماسكًا بين الصفحات، ومئات الرسوم التوضيحية الجديدة لشرح كيفية عمل Next.js بصريًا. +* **المزيد قادم**: لدينا المزيد من العمل هنا. يعمل فريق تجربة المطور (Developer Experience) في Vercel بجد لتوفير موارد تعليمية إضافية (بما في ذلك دورة محدثة على `/learn` لتعليم موجه التطبيق) وأمثلة على أكواد واقعية (بما في ذلك إعادة كتابة [Next.js Commerce](https://github.com/vercel/commerce)). + +سنصدر محتوى جديدًا في [الوثائق](/docs)، وعلى [تويتر](https://twitter.com/nextjs)، و[يوتيوب](https://www.youtube.com/c/VercelHQ)، والمزيد. + +### [ميزات React الجديدة](#new-react-features) + +لقد سمعنا أيضًا ملاحظاتكم حول التعليم حول ميزات React الجديدة المتوفرة في موجه التطبيق لـ Next.js. + +* **مكونات الخادم (Server Components)**: من المهم ملاحظة أن ميزات مثل مكونات الخادم واتفاقيات مثل توجيه [`"use client"`](https://github.com/reactjs/rfcs/blob/main/text/0227-server-module-conventions.md) ليست خاصة بـ Next.js، ولكنها جزء أكبر من نظام React البيئي. + + يعمل فريقنا وشركاؤنا في Meta ومساهمون مستقلون آخرون على توفير المزيد من التعليم حول هذه المواضيع. إنها أيام مبكرة لهذه المفاهيم، لكننا واثقون في نظام React البيئي و[التعليم المستمر](https://github.com/reactwg/server-components/discussions/5). + +* **مكونات العميل (Client Components)**: مع الحديث الأخير حول مكونات الخادم، من المهم ملاحظة أن مكونات العميل ليست _إزالة تحسين_. العميل جزء صالح من نموذج React ولن يختفي. + + يمكنك التفكير في مكونات العميل كنظام Next.js البيئي الحالي، حيث تستمر المكتبات والأدوات المفضلة لديك في العمل. على سبيل المثال، سؤال شائع رأيناه هو ما إذا كان يجب إضافة `"use client"` إلى كل ملف لجعله مكون عميل. هذا ليس ضروريًا، لكننا نفهم أن هذه المفاهيم جديدة وستستغرق وقتًا للتعلم. تحتاج فقط إلى [وضع علامة على الحد الأعلى](/docs/getting-started/react-essentials#the-use-client-directive) حيث ينتقل الكود بين الخادم والعميل. تسمح هذه البنية لك [بدمج مكونات الخادم والعميل معًا](https://github.com/reactwg/server-components/discussions/5). + +* **نظام بيئي تابع لجهات خارجية في نمو**: بالإضافة إلى التعليم، لا يزال النظام البيئي حول ميزات React الأحدث في نمو. على سبيل المثال، أعلنت [Panda CSS](https://panda-css.com/)، مكتبة CSS-in-JS من صانعي Chakra UI، مؤخرًا عن دعم مكونات خادم React. + +* **إجراءات الخادم (Alpha)**: تمكن [إجراءات الخادم](/docs/app/building-your-application/data-fetching/server-actions) تحويلات بيانات جانب الخادم، وتقليل JavaScript جانب العميل، والنماذج المحسنة تدريجيًا. لا نوصي باستخدام إجراءات الخادم في الإنتاج بعد. نقدر الملاحظات المبكرة من مستخدمي الإصدار التجريبي الذين يساعدوننا في تشكيل مستقبل هذه الميزة. + + +[شكرًا لكم](#thank-you) +----------------------- + +نشكر الكثير منكم لاختياركم التعلم والبناء باستخدام Next.js. + +سيظهر تركيزنا على الأداء والاستقرار وتجربة المطور في الإصدارات القادمة من Next.js. نريد أن يكون استخدام Next.js ممتعًا - وأن يجعلكم (وفريقكم) أكثر إنتاجية. + +كالعادة، نقدر ملاحظاتكم كثيرًا. إذا واجهتم أي مشكلات مع Next.js، يرجى [فتح مشكلة](https://github.com/vercel/next.js/issues/new/choose)، أو [بدء مناقشة جديدة](https://github.com/vercel/next.js/discussions)، وسنقوم بالتحقيق. \ No newline at end of file diff --git a/apps/docs/content/ar/blog/layouts-rfc.mdx b/apps/docs/content/ar/blog/layouts-rfc.mdx new file mode 100644 index 00000000..d4591ecd --- /dev/null +++ b/apps/docs/content/ar/blog/layouts-rfc.mdx @@ -0,0 +1,910 @@ +--- +source-updated-at: 2025-05-29T19:07:21.000Z +translation-updated-at: 2025-06-02T19:48:45.567Z +title: طلب تعليقات (RFC) حول التخطيطات +description: >- + مسارات متداخلة وتخطيطات، توجيه من جانب الخادم والعميل، ميزات React 18، ومصممة لمكونات الخادم. +author: + - name: ديلبا دي أوليفيرا + image: /static/team/delba.jpg + - name: لي روبنسون + image: /static/team/lee.jpg + - name: سيباستيان ماركبيج + image: /static/team/seb.jpg + - name: تيم نيوتركينز + image: /static/team/tim.jpg +date: 2022-05-23T20:30:00.507Z +image: >- + https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/twitter-card.png +--- + +يحدد هذا الطلب للتعليقات (RFC) أكبر تحديث لـ Next.js منذ إطلاقه في 2016: + +* **التخطيطات المتداخلة:** بناء تطبيقات معقدة بمسارات متداخلة. +* **مصممة لمكونات الخادم:** مُحسنة لتنقل الشجرة الفرعية. +* **تحسين جلب البيانات:** جلب البيانات في التخطيطات مع تجنب الشلالات. +* **استخدام ميزات React 18:** البث، التحولات، و Suspense. +* **التوجيه من جانب الخادم والعميل:** توجيه مركزي للخادم مع سلوك يشبه **تطبيق الصفحة الواحدة (SPA)**. +* **قابلية التبني بنسبة 100% تدريجياً:** لا توجد تغييرات كاسحة حتى تتمكن من التبني تدريجياً. +* **أنماط توجيه متقدمة:** مسارات متوازية، مسارات متقاطعة، والمزيد. + +سيتم بناء موجه Next.js الجديد على أساس [ميزات React 18 التي تم إصدارها مؤخراً](https://reactjs.org/blog/2022/03/29/react-v18.html). نخطط لإدخال إعدادات افتراضية واتفاقيات تسمح لك بتبني هذه الميزات الجديدة بسهولة والاستفادة من المزايا التي توفرها. + +> العمل على هذا الطلب للتعليقات مستمر وسنعلن عندما تصبح الميزات الجديدة متاحة. لتقديم ملاحظاتك، انضم إلى النقاش على [مناقشات GitHub](https://github.com/vercel/next.js/discussions/37136). + +[جدول المحتويات](#جدول-المحتويات) +--------------------------------------- + +* [الهدف](#الهدف) +* [المصطلحات](#المصطلحات) +* [كيف يعمل التوجيه حالياً](#كيف-يعمل-التوجيه-حالياً) +* [دليل `app`](#تقديم-موجه-app) +* [تحديد المسارات](#تحديد-المسارات) +* [التخطيطات](#التخطيطات) +* [الصفحات](#الصفحات) +* [مكونات خادم React](#مكونات-خادم-react) +* [جلب البيانات](#جلب-البيانات) +* [مجموعات المسار (جديدة)](#مجموعات-المسار) +* [التوجيه المركزي للخادم (جديد)](#التوجيه-المركزي-للخادم) +* [حالات التحميل الفوري (جديدة)](#حالات-التحميل-الفوري) +* [معالجة الأخطاء (جديدة)](#معالجة-الأخطاء) +* [القوالب (جديدة)](#القوالب) +* [أنماط التوجيه المتقدمة (جديدة)](#أنماط-التوجيه-المتقدمة) +* [الختام](#الختام) + +[الهدف](#الهدف) +------------------------- + +لقد كنا نجمع ملاحظات المجتمع من GitHub وDiscord وReddit واستطلاع المطورين حول القيود الحالية للتوجيه في Next.js. وجدنا أن: + +* يمكن تحسين تجربة المطور في إنشاء التخطيطات. يجب أن يكون من السهل إنشاء تخطيطات يمكن تداخلها ومشاركتها عبر المسارات والحفاظ على حالتها أثناء التنقل. +* العديد من تطبيقات Next.js هي لوحات تحكم أو وحدات تحكم، والتي ستستفيد من حلول التوجيه الأكثر تطوراً. + +بينما عمل نظام التوجيه الحالي بشكل جيد منذ بداية Next.js، نريد تسهيل بناء تطبيقات ويب أكثر أداءً وغنية بالميزات للمطورين. + +كمشرفين على الإطار، نريد أيضاً بناء نظام توجيه متوافق مع الإصدارات السابقة ويتوافق مع مستقبل React. + +> **ملاحظة:** استوحيت بعض اتفاقيات التوجيه من الموجه القائم على Relay في Meta، حيث تم تطوير بعض ميزات مكونات الخادم أصلاً، وكذلك موجهات جانب العميل مثل React Router وEmber.js. استوحيت اتفاقية ملف `layout.js` من العمل المنجز في SvelteKit. نود أيضاً أن نشكر [كاسيدي](https://twitter.com/cassidoo) لفتحها [طلب تعليقات سابق حول التخطيطات](https://github.com/vercel/next.js/discussions/26389). + +[المصطلحات](#المصطلحات) +--------------------------- + +يقدم هذا الطلب للتعليقات اتفاقيات وبناء جملة جديد للتوجيه. المصطلحات مبنية على React والمصطلحات القياسية لمنصة الويب. خلال الطلب، ستشاهد هذه المصطلحات مرتبطة بتعريفاتها أدناه. + +* **الشجرة:** اتفاقية لتصور هيكل هرمي. على سبيل المثال، شجرة مكونات مع مكونات أب وأبناء، هيكل مجلد، إلخ. +* **الشجرة الفرعية:** جزء من الشجرة، يبدأ من الجذر (الأول) وينتهي عند الأوراق (الأخير). + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/terminology.png) + +* **مسار URL:** جزء من عنوان URL يأتي بعد النطاق. +* **مقطع URL:** جزء من مسار URL محدد بشرطات مائلة. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/url-anatomy.png) + +[كيف يعمل التوجيه حالياً](#كيف-يعمل-التوجيه-حالياً) +----------------------------------------------------------- + +اليوم، يستخدم Next.js نظام الملفات لتعيين المجلدات والملفات الفردية في دليل [الصفحات](/docs/pages/building-your-application/routing/pages-and-layouts) إلى مسارات يمكن الوصول إليها عبر عناوين URL. كل ملف **صفحة** يصدر مكون React وله **مسار** مرتبط بناءً على اسم الملف. على سبيل المثال: + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/routing-today.png) + +* **المسارات الديناميكية:** يدعم Next.js [المسارات الديناميكية](/docs/pages/building-your-application/routing/dynamic-routes) (بما في ذلك الاختلافات الشاملة) مع اتفاقيات `[param].js`، `[...param].js` و `[[...param]].js`. +* **التخطيطات:** يقدم Next.js دعمًا للتخطيطات البسيطة [القائمة على المكونات](/docs/pages/building-your-application/routing/pages-and-layouts#layout-pattern)، وتخطيطات لكل صفحة باستخدام نمط [خاصية المكون](/docs/pages/building-your-application/routing/pages-and-layouts#layout-pattern#per-page-layouts)، وتخطيط عالمي واحد باستخدام [تطبيق مخصص](/docs/pages/building-your-application/routing/pages-and-layouts#layout-pattern#single-shared-layout-with-custom-app). +* **جلب البيانات:** يوفر Next.js طرق جلب البيانات ([`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props)، [`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props)) التي يمكن استخدامها على مستوى الصفحة (المسار). تُستخدم هذه الطرق لتحديد ما إذا كانت الصفحة يجب أن يتم إنشاؤها بشكل ثابت ([`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props)) أو تقديمها من جانب الخادم ([`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props)). بالإضافة إلى ذلك، يمكنك استخدام [التجديد الثابت التدريجي (ISR)](/docs/pages/building-your-application/data-fetching/incremental-static-regeneration) لإنشاء أو تحديث الصفحات الثابتة بعد بناء الموقع. +* **التقديم:** يوفر Next.js ثلاث خيارات للتقديم: [التوليد الثابت](https://nextjs.org/learn/foundations/how-nextjs-works/rendering)، [التقديم من جانب الخادم](https://nextjs.org/learn/foundations/how-nextjs-works/rendering)، و[التقديم من جانب العميل](https://nextjs.org/learn/foundations/how-nextjs-works/rendering). افتراضياً، يتم توليد الصفحات بشكل ثابت ما لم يكن لديها متطلبات جلب بيانات معيقة (`getServerSideProps`). + +[تقديم دليل `app`](#تقديم-دليل-app) +----------------------------------------------------------------- + +لضمان إمكانية تبني هذه التحسينات الجديدة تدريجياً وتجنب التغييرات الكاسحة، نقترح دليلاً جديداً يسمى `app`. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/app-folder.png) + +سيعمل دليل `app` جنباً إلى جنب مع دليل `pages`. يمكنك نقل أجزاء من تطبيقك تدريجياً إلى دليل `app` الجديد للاستفادة من الميزات الجديدة. للتوافق مع الإصدارات السابقة، سيظل سلوك دليل `pages` كما هو وسيستمر في الحصول على الدعم. + +[تحديد المسارات](#تحديد-المسارات) +----------------------------------- + +يمكنك استخدام **التسلسل الهرمي للمجلدات** داخل `app` لتحديد المسارات. **المسار** هو مسار واحد من المجلدات المتداخلة، يتبع التسلسل الهرمي من **مجلد الجذر** وصولاً إلى **مجلد الورقة** النهائي. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/routes.png) + +على سبيل المثال، يمكنك إضافة مسار جديد `/dashboard/settings` عن طريق تداخل مجلدين جديدين في دليل `app`. + +> **ملاحظة:** +> +> * مع هذا النظام، ستستخدم المجلدات لتحديد المسارات، والملفات لتحديد واجهة المستخدم (مع اتفاقيات ملفات جديدة مثل `layout.js`، `page.js`، وفي الجزء الثاني من الطلب `loading.js`). +> * يسمح لك ذلك بوضع ملفات مشروعك الخاصة (مكونات واجهة المستخدم، ملفات الاختبار، القصص، إلخ) داخل دليل `app`. حالياً، هذا ممكن فقط مع [تهيئة pageExtensions](/docs/pages/api-reference/next-config-js/pageExtensions#including-non-page-files-in-the-pages-directory). + +### [مقاطع المسار](#مقاطع-المسار) + +يمثل كل مجلد في [الشجرة الفرعية](#المصطلحات) **مقطع مسار**. يتم تعيين كل مقطع مسار إلى **مقطع** مقابِل في **[مسار URL](#المصطلحات)**. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/route-segments.png) + +على سبيل المثال، يتكون مسار `/dashboard/settings` من 3 مقاطع: + +* مقطع الجذر `/` +* مقطع `dashboard` +* مقطع `settings` + +> **ملاحظة**: تم اختيار اسم **مقطع المسار** لمطابقة المصطلحات الحالية حول [مسارات URL](#المصطلحات). + +[التخطيطات](#التخطيطات) +------------------- + +**اتفاقية ملف جديدة:** `layout.js` + +حتى الآن، استخدمنا المجلدات لتحديد مسارات تطبيقنا. لكن المجلدات الفارغة لا تفعل أي شيء بمفردها. دعونا نناقش كيف يمكنك تحديد واجهة المستخدم التي سيتم تقديمها لهذه المسارات باستخدام اتفاقيات ملفات جديدة. + +**التخطيط** هو واجهة مستخدم مشتركة بين مقاطع المسار في [شجرة فرعية](#المصطلحات). لا تؤثر التخطيطات على [مسارات URL](#المصطلحات) ولا يتم إعادة تقديمها (يتم الحفاظ على حالة React) عندما يتنقل المستخدم بين المقاطع الشقيقة. + +يمكن تعريف التخطيط عن طريق تصدير مكون React افتراضي من ملف `layout.js`. يجب أن يقبل المكون خاصية `children` التي سيتم ملؤها بالمقاطع التي يحيط بها التخطيط. + +هناك نوعان من التخطيطات: + +* **تخطيط الجذر:** ينطبق على جميع المسارات +* **التخطيط العادي:** ينطبق على مسارات محددة + +يمكنك تداخل تخطيطين أو أكثر معاً لتشكيل **تخطيطات متداخلة**. + +### [تخطيط الجذر](#تخطيط-الجذر) + +يمكنك إنشاء تخطيط جذر ينطبق على جميع مسارات تطبيقك عن طريق إضافة ملف `layout.js` داخل مجلد `app`. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/root-layout.png) + +> **ملاحظة:** +> +> * يحل تخطيط الجذر محل الحاجة إلى [تطبيق مخصص (_app.js)](/docs/pages/building-your-application/routing/custom-app) و[مستند مخصص (_document.js)](/docs/pages/building-your-application/routing/custom-document) لأنه ينطبق على جميع المسارات. +> * ستتمكن من استخدام تخطيط الجذر لتخصيص غلاف المستند الأولي (مثل علامات `` و ``). +> * ستتمكن من جلب البيانات داخل تخطيط الجذر (والتخطيطات الأخرى). + +### [التخطيطات العادية](#التخطيطات-العادية) + +يمكنك أيضاً إنشاء تخطيط ينطبق فقط على جزء من تطبيقك عن طريق إضافة ملف `layout.js` داخل مجلد معين. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/regular-layouts.png) + +على سبيل المثال، يمكنك إنشاء ملف `layout.js` داخل مجلد `dashboard` الذي سينطبق فقط على مقاطع المسار داخل `dashboard`. + +### [تداخل التخطيطات](#تداخل-التخطيطات) + +التخطيطات **متداخلة** افتراضياً. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/nested-layouts.png) + +على سبيل المثال، إذا أردنا دمج التخطيطين أعلاه. سيتم تطبيق تخطيط الجذر (`app/layout.js`) على تخطيط `dashboard`، والذي سيتم تطبيقه أيضاً على جميع مقاطع المسار داخل `dashboard/*`. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/nested-layouts-example.png) + +[الصفحات](#الصفحات) +--------------- + +**اتفاقية ملف جديدة:** `page.js` + +الصفحة هي واجهة مستخدم فريدة لمقطع مسار. يمكنك إنشاء صفحة عن طريق إضافة ملف `page.js` داخل مجلد. + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/page.png) + +على سبيل المثال، لإنشاء صفحات لمسارات `/dashboard/*`، يمكنك إضافة ملف `page.js` داخل كل مجلد. عندما يزور المستخدم `/dashboard/settings`، سيقدم Next.js ملف `page.js` لمجلد `settings` ملفوفاً في أي تخطيطات موجودة أعلى [الشجرة الفرعية](#المصطلحات). + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/page-example.png) + +يمكنك إنشاء ملف `page.js` مباشرة داخل مجلد dashboard لمطابقة مسار `/dashboard`. سيتم تطبيق تخطيط dashboard أيضاً على هذه الصفحة: + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/page-nested.png) + +يتكون هذا المسار من مقطعين: + +* مقطع الجذر `/` +* مقطع `dashboard` + +> **ملاحظة:** +> +> * لكي يكون المسار صالحاً، يجب أن يحتوي على صفحة في مقطع الورقة الخاص به. إذا لم يكن كذلك، فسيؤدي المسار إلى خطأ. + +### [سلوك التخطيط والصفحة](#سلوك-التخطيط-والصفحة) + +* يمكن استخدام امتدادات الملفات `js|jsx|ts|tsx` للصفحات والتخطيطات. +* مكونات الصفحة هي التصدير الافتراضي لـ `page.js`. +* مكونات التخطيط هي التصدير الافتراضي لـ `layout.js`. +* يجب أن تقبل مكونات التخطيط خاصية `children`. + +عند تقديم مكون التخطيط، سيتم ملء خاصية `children` بتخطيط فرعي (إذا كان موجوداً في [الشجرة الفرعية](#المصطلحات) أدناه) أو بصفحة. + +قد يكون من الأسهل تصورها كشجرة تخطيط حيث سيختار التخطيط الأصل أقرب تخطيط فرعي حتى يصل إلى صفحة. + +**مثال:** + +![](https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/layouts-rfc/basic-example.png) + +```js filename="app/layout.js" +// تخطيط الجذر +// - ينطبق على جميع المسارات +export default function RootLayout({ children }) { + return ( + + +
+ {children} +