Merge branch 'main' into fix/update-content-collections

src/content/docs/ar/guides/fonts.mdx

@@ -0,0 +1,148 @@
+---
+title: استخدام الخطوط المخصصة
+sidebar:
+  label: الخطوط
+description: >
+  هل ترغب في إضافة خطوط مخصصة إلى موقع ويب Astro؟
+  يمكنك استخدام Google Fonts مع Fontsource أو إضافة أي خط من اختيارك بسهولة.
+i18nReady: true
+---
+import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
+import { Steps } from '@astrojs/starlight/components'
+
+سيرشدك هذا الدليل إلى كيفية إضافة خطوط الويب إلى مشروعك واستخدامها في مكوناتك.
+
+## استخدام ملف خط محلي
+
+سيوضح هذا المثال كيفية إضافة خط مخصص باستخدام ملف الخط `DistantGalaxy.woff`.
+
+<Steps>
+
+1. أضف ملف الخط إلى `public/fonts/`.
+
+2. أضف البيان التالي `@font-face` إلى CSS الخاص بك. يمكن أن يكون ذلك في ملف `.css` عام تستورده، أو في كتلة `<style is:global>`, أو في كتلة `<style>` في تصميم أو مكون معين حيث تريد استخدام هذا الخط.
+
+    ```css
+    /*  قم بتسجيل خطك المخصص وأخبر المتصفح بمكان العثور عليه.*/
+    @font-face {
+      font-family: 'DistantGalaxy';
+      src: url('/fonts/DistantGalaxy.woff') format('woff');
+      font-weight: normal;
+      font-style: normal;
+      font-display: swap;
+    }
+    ```
+
+3. استخدم قيمة `font-family` من بيان `@font-face` لتنسيق العناصر في المكون أو التخطيط الخاص بك. في هذا المثال، سيحصل العنوان `<h1>` على الخط المخصص، بينما لن يتأثر الفقرة `<p>`.
+
+    ```astro title="src/pages/example.astro" {9-11}
+    ---
+    ---
+    <h1>في مجرة بعيدة، بعيدة جداً...</h1>
+
+    <p>الخطوط المخصصة تجعل العناوين أكثر روعة!</p>
+
+    <style>
+    h1 {
+     font-family: 'DistantGalaxy', sans-serif;
+    }
+    </style>
+    ```
+
+</Steps>
+
+
+## استخدام Fontsource
+
+يُبسط مشروع [Fontsource](https://fontsource.org/) استخدام خطوط Google والخطوط مفتوحة المصدر الأخرى. يوفر وحدات npm التي يمكنك تثبيتها للخطوط التي ترغب في استخدامها.
+
+<Steps>
+
+1. ابحث عن الخط الذي تريد استخدامه في [كتالوج Fontsource](https://fontsource.org/). في هذا المثال، سيتم استخدام [Twinkle Star](https://fontsource.org/fonts/twinkle-star).
+
+2. قم بتثبيت الحزمة الخاصة بالخط الذي اخترته باستخدام أداة إدارة الحزم مثل npm، pnpm أو yarn.
+
+    <PackageManagerTabs>
+      <Fragment slot="npm">
+      ```shell
+      npm install @fontsource/twinkle-star
+      ```
+      </Fragment>
+      <Fragment slot="pnpm">
+      ```shell
+      pnpm add @fontsource/twinkle-star
+      ```
+      </Fragment>
+      <Fragment slot="yarn">
+      ```shell
+      yarn add @fontsource/twinkle-star
+      ```
+      </Fragment>
+    </PackageManagerTabs>
+
+    :::tip
+    ستجد اسم الحزمة الصحيح في قسم "التثبيت السريع" في كل صفحة خط على موقع Fontsource. سيبدأ بـ `@fontsource/` أو `@fontsource-variable/` يليه اسم الخط.
+    :::
+
+3. استورد حزمة الخط في المكون الذي ترغب في استخدام الخط فيه. عادةً، يجب أن تقوم بذلك في مكون تخطيط مشترك لضمان توفر الخط عبر موقعك.
+
+    سيقوم الاستيراد بإضافة القواعد اللازمة لـ `@font-face` تلقائيًا لإعداد الخط.
+
+    ```astro title="src/layouts/BaseLayout.astro"
+    ---
+    import '@fontsource/twinkle-star';
+    ---
+    ```
+
+4. استخدم اسم الخط كما هو موضح في مثال `body` في صفحة Fontsource كقيمة لـ `font-family`. هذا سيعمل في أي مكان يمكنك كتابة CSS فيه في مشروعك باستخدام Astro.
+
+    ```css
+    h1 {
+      font-family: "Twinkle Star", cursive;
+    }
+    ```
+
+</Steps>
+
+لتحسين أوقات عرض موقعك، قد ترغب في تحميل الخطوط الأساسية التي تحتاجها الصفحة في البداية. راجع [دليل Fontsource لتحميل الخطوط مسبقًا](https://fontsource.org/docs/getting-started/preload) لمزيد من المعلومات والاستخدام.
+
+## تسجيل الخطوط في Tailwind
+
+إذا كنت تستخدم [تكامل Tailwind](/ar/guides/integrations-guide/tailwind/)، يمكنك استخدام أي من الطرق السابقة في هذه الصفحة لتثبيت الخط، مع بعض التعديلات. يمكنك إما إضافة جملة [`@font-face` لخط محلي](#استخدام-ملف-خط-محلي) أو استخدام [استراتيجية الاستيراد الخاصة بـ Fontsource](#استخدام-fontsource) لتثبيت خطك.
+
+لتسجيل خطك في Tailwind:
+
+<Steps>
+
+1. اتبع أيًا من الأدلة السابقة، ولكن تخطَّ الخطوة الأخيرة من إضافة `font-family` إلى CSS.
+
+2. أضف اسم الخط إلى `tailwind.config.mjs`.
+
+    هذا المثال يضيف `Inter` إلى مجموعة الخطوط بدون سيريف، مع الخطوط الاحتياطية الافتراضية من Tailwind CSS.
+
+    ```js title="tailwind.config.mjs" ins={1,8-10}
+    import defaultTheme from 'tailwindcss/defaultTheme'
+
+    /** @type {import('tailwindcss').Config} */
+    export default {
+    	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
+    	theme: {
+    		extend: {
+    			fontFamily: {
+    				sans: ['Inter', ...defaultTheme.fontFamily.sans],
+    			},
+    		},
+    	},
+    	plugins: [],
+    }
+    ```
+
+    الآن، سيستخدم كل النص بدون سيريف (الافتراضي في Tailwind) في مشروعك الخط الذي اخترته، وستقوم أيضًا فئة `font-sans` بتطبيق خط Inter.
+</Steps>
+
+راجع [توثيق Tailwind حول إضافة عائلات الخطوط المخصصة](https://tailwindcss.com/docs/font-family#using-custom-values) لمزيد من المعلومات.
+
+## المزيد من الموارد
+
+- تعرف على كيفية عمل خطوط الويب في [دليل MDN لخطوط الويب](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts).
+- توليد CSS لخطك باستخدام [مولد الخطوط الويب من Font Squirrel](https://www.fontsquirrel.com/tools/webfont-generator).

src/content/docs/en/tutorial/6-islands/2.mdx

@@ -106,8 +106,9 @@ To add interactivity to an Astro component, you can use a `<script>` tag. This s
 
     <script is:inline>
       const theme = (() => {
-        if (typeof localStorage !== 'undefined' && localStorage.getItem('theme')) {
-          return localStorage.getItem('theme') ?? "light";
+        const localStorageTheme = localStorage?.getItem("theme") ?? '';
+        if (['dark', 'light'].includes(localStorageTheme)) {
+          return localStorageTheme;
         }
         if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
           return 'dark';

src/content/docs/fr/tutorial/6-islands/2.mdx

@@ -106,8 +106,9 @@ Pour ajouter de l'interactivité à un composant Astro, vous pouvez utiliser une
 
     <script is:inline>
       const theme = (() => {
-        if (typeof localStorage !== 'undefined' && localStorage.getItem('theme')) {
-          return localStorage.getItem('theme') ?? "light";
+        const localStorageTheme = localStorage?.getItem("theme") ?? '';
+        if (['dark', 'light'].includes(localStorageTheme)) {
+          return localStorageTheme;
         }
         if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
           return 'dark';

src/content/docs/ko/tutorial/6-islands/2.mdx

@@ -107,8 +107,9 @@ Astro 컴포넌트에 상호작용을 추가하려면 `<script>` 태그를 사
 
     <script is:inline>
       const theme = (() => {
-        if (typeof localStorage !== 'undefined' && localStorage.getItem('theme')) {
-          return localStorage.getItem('theme') ?? "light";
+        const localStorageTheme = localStorage?.getItem("theme") ?? '';
+        if (['dark', 'light'].includes(localStorageTheme)) {
+          return localStorageTheme;
         }
         if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
           return 'dark';

src/content/docs/zh-cn/guides/fonts.mdx

@@ -1,5 +1,7 @@
 ---
 title: 使用自定义字体
+sidebar:
+  label: 字体
 description: >-
   想要为 Astro 生成的网站添加一些自定义的字体？
   使用 Google Fonts 或者使用本地文件以添加自定义字体。

src/content/docs/zh-cn/reference/experimental-flags/client-prerender.mdx

@@ -0,0 +1,41 @@
+---
+title: 实验性客户端预渲染
+sidebar:
+  label: 客户端预渲染
+i18nReady: true
+---
+
+import Since from '~/components/Since.astro'
+
+<p>
+
+**类型：** `boolean`<br />
+**默认值：** `false`<br />
+<Since v="4.2.0" />
+</p>
+
+在支持的浏览器中，对客户端上的预获取（prefetch）页面启用预渲染。
+
+该功能使用了实验性的 [推测规则 web API](https://developer.mozilla.org/zh-CN/docs/Web/API/Speculation_Rules_API) 并全局增强了默认的 `prefetch` 行为来预渲染客户端上的链接。
+在启用该功能之前，你可能需要考虑一下 [在客户端上进行预渲染的风险](https://developer.mozilla.org/zh-CN/docs/Web/API/Speculation_Rules_API#不安全的预取)。
+
+在 `astro.config.mjs` 中启用客户端预渲染以及任何所需的 `prefetch` 配置选项：
+
+```js
+// astro.config.mjs
+{
+  prefetch: {
+    prefetchAll: true,
+    defaultStrategy: 'viewport',
+  },
+	experimental: {
+		clientPrerender: true,
+	},
+}
+```
+
+然后在网站上的任意 `<a />` 链接上使用 `data-astro-prefetch` 属性来选用预获取。这会在 `<script>` 标签上附加相应的推测规则，而不是将 `<link>` 标签附加到页面的 head 部分或使用 JavaScript 来获取页面。
+
+客户端预渲染需要浏览器的支持。如果推测规则 API 不被支持，那么 `prefetch` 将会回退到支持的策略。
+
+有关 `prefetch` 的更多选项和使用方法，请参阅 [预获取指南](/zh-cn/guides/prefetch/)。

src/content/docs/zh-cn/reference/experimental-flags/content-intellisense.mdx

@@ -0,0 +1,29 @@
+---
+title: 用于内容集合的实验性 IntelliSense
+sidebar:
+  label: 用于集合的 Intellisense
+i18nReady: true
+---
+
+import Since from '~/components/Since.astro'
+
+<p>
+
+**类型：** `boolean`<br />
+**默认值：** `false`<br />
+<Since v="4.14.0" />
+</p>
+
+在能兼容的编辑器中为你的内容集合条目启用 IntelliSense 功能（例如：代码补全，快速提示）。
+
+启用后，此功能将生成 JSON 结构并将其添加到项目中的 `.astro` 目录中。这些文件能被 Astro 语言服务器调用以在内容文件（`.md`、`.mdx`、`.mdoc`）中提供 Intellisense。
+
+```js
+{
+  experimental: {
+    contentIntellisense: true,
+  },
+}
+```
+
+要将此功能与 Astro VS Code 扩展一起使用，你还必须在 VS Code 设置中启用 `astro.content-intellisense` 选项。而对于直接使用 Astro 语言服务器的编辑器，请传递 `contentIntellisense: true` 初始化参数来启用此功能。

src/content/docs/zh-cn/reference/experimental-flags/svg.mdx

@@ -0,0 +1,100 @@
+---
+title: 实验性 SVG 组件
+sidebar:
+  label: SVG 组件
+i18nReady: true
+---
+
+import Since from '~/components/Since.astro'
+
+<p>
+
+**类型：** `boolean`<br />
+**默认值：** `false`<br />
+<Since v="5.0.0" />
+</p>
+
+该功能允许你导入 SVG 文件并将其作为 Astro 组件来使用。默认情况下，Astro 会将 SVG 内容内联到你的 HTML 输出中。
+
+要启用该功能，请在你的 Astro 配置中将 `experimental.svg` 设置为 `true`。
+
+ ```js
+{
+  experimental: {
+    svg: true,
+  },
+}
+```
+
+要使用该功能，请引用任意本地 `.svg` 文件的默认导入。由于此导入会被视为 Astro 组件，因此需要使用与 [使用动态标签](/zh-cn/reference/astro-syntax/#动态标签) 时相同的约定（例如：大写）。
+
+```astro
+---
+import Logo from './path/to/svg/file.svg';
+---
+
+<Logo />
+```
+
+## SVG 组件属性
+
+你可以传入诸如 `width`、`height`、`fill`、`stroke` 这样的属性，以及任何 [原生的 `<svg>` 元素](https://developer.mozilla.org/zh-CN/docs/Web/SVG/Element/svg) 接受的其他属性。这些属性将自动应用于底层的 `<svg>` 元素。如果原有的 `.svg` 文件中已有某个将要传递给组件的属性，那么这个原有值将会被传入值覆盖。
+
+```astro
+---
+import Logo from '../assets/logo.svg';
+---
+
+<Logo width={64} height={64} fill="currentColor" />
+```
+
+### `size`
+
+为了方便起见，SVG 组件还接受 `size` 属性。 `size` 是将 `width` 和 `height` 属性设置为相同值的简写方式。
+
+以下示例使用 Astro 的 `size` 属性将宽度和高度设置为相同的 48，而无需分别设置 HTML `<svg>` 属性的 `width` 和 `height`：
+
+```astro
+<!-- 使用 size 属性来设置相同的宽度和高度 -->
+<Logo size={48} />
+```
+
+### `mode`
+
+在任意 SVG 组件上添加 `mode` 属性，以覆盖你默认配置的 `svg.mode` 技术来处理导入的 SVG 文件。
+
+以下示例生成了一个精灵序列图，而不是将图标的 SVG 内容内联到 HTML 输出中：
+
+```astro
+---
+import Logo from '../assets/logo.svg';
+---
+
+<Logo size={64} mode="sprite" />
+```
+
+## experimental.svg.mode
+
+<p>
+
+**类型：** `string`<br />
+**默认值：** `'inline'`<br />
+<Since v="5.0.0" />
+</p>
+
+处理导入的 SVG 文件的默认技术。如果未指定，Astro 会将 SVG 内容内联到 HTML 输出中。
+
+ ```js
+{
+  experimental: {
+    svg: {
+      mode: 'sprite',
+    }
+  },
+}
+```
+
+- `inline`：Astro 会将 SVG 内容内联到你的 HTML 输出中。（默认）
+- `sprite`：Astro 将生成包含所有导入的 SVG 文件的精灵序列图。
+
+有关完整概述以及对此实验性 API 的反馈，请参阅 [SVG 功能 RFC](https://github.com/withastro/roadmap/pull/1035)。

src/content/i18n/zh-TW.yml

@@ -65,6 +65,9 @@ starlight.title: 想要建立自己的文件嗎？
 starlight.description: 獲取此模版即可開始。
 # `<StudioHeading>` component
 studioHeading.label: Studio 功能
+# Upgrade guide
+upgrade.implementationPR: '實作 PR：'
+
 # DocSearch component strings
 docsearch.button: 搜尋
 docsearch.placeholder: 搜尋文件