i18n(zh-cn): Update typescript.mdx and related pages (#12400)

Co-authored-by: Yan <[email protected]>

Author: liruifengv

src/content/docs/zh-cn/guides/integrations-guide/alpinejs.mdx

@@ -9,7 +9,8 @@ category: renderer
 i18nReady: true
 ---
 
-import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
+import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
+import Since from '~/components/Since.astro';
 
 这个 **[Astro 集成][astro-integration]** 将 [Alpine.js](https://alpinejs.dev/) 添加到你的项目中，这样你就可以在页面的任何位置使用 Alpine.js。
 
@@ -97,7 +98,13 @@ export default defineConfig({
 
 ### `entrypoint`
 
-请查阅我们的 [Astro 集成文档][astro-integration] 了解更多关于集成的信息。
+<p>
+
+**类型：** `string`<br />
+<Since v="0.4.0" pkg="@astrojs/alpinejs" />
+</p>
+
+
 你可以通过设置 `entrypoint` 选项为与根目录相关的的导入说明符（例如 `entrypoint: "/src/entrypoint"`）来扩展 Alpine。
 
 这个文件的默认导出应该是一个函数，该函数接收一个在应用启动前的 Alpine 实例作为参数。这样做可以在高级用例中允许使用自定义指令、插件以及其他自定义功能。
@@ -149,7 +156,7 @@ export default (Alpine: Alpine) => {
 
 ## TypeScript 的智能提示
 
-`@astrojs/alpine` 集成会将 `Alpine` 对象添加到全局的 `window` 对象中。为了在你的开发环境中获得 `Alpine` 的自动完成提示，你需要在 `src/env.d.ts` 文件中添加如下代码：
+`@astrojs/alpine` 集成会将 `Alpine` 对象添加到 [全局的 `window` 对象](/zh-cn/guides/typescript/#window-和-globalthis) 中。为了在你的开发环境中获得 `Alpine` 的自动完成提示，你需要在 `src/env.d.ts` 文件中添加如下代码：
 
 ```ts title="src/env.d.ts"
 interface Window {

src/content/docs/zh-cn/guides/integrations-guide/cloudflare.mdx

@@ -424,7 +424,7 @@ Cloudflare 的环境变量和私密环境变量与 [`astro:env` API](/zh-cn/guid
 ```
 :::
 
-你可以使用 `Runtime` 来为 `runtime` 对象添加类型：
+你可以使用 `Runtime` [扩展全局类型](/zh-cn/guides/typescript/#扩展全局类型) 来为 `runtime` 对象添加类型：
 
 ```ts title="src/env.d.ts"
 type Runtime = import('@astrojs/cloudflare').Runtime<Env>;

src/content/docs/zh-cn/guides/integrations-guide/vercel.mdx

@@ -99,10 +99,12 @@ vercel deploy --prebuilt
 要配置这个适配器，将一个对象传递给 `astro.config.mjs` 中的 `vercel()` 函数调用：
 
 ### `webAnalytics`
+<p>
 
 **类型：** `VercelWebAnalyticsConfig`<br/>
 **适用于：** Serverless, Static<br/>
 <Since v="3.8.0" pkg="@astrojs/vercel" />
+</p>
 
 对于 `@vercel/[email protected]` 或更早的版本时，你可以在 Astro 配置中设置 `webAnalytics： { enabled： true }` 以将 Vercel 的跟踪脚本注入到你所有的页面中。
 
@@ -124,9 +126,12 @@ export default defineConfig({
 
 ### `imagesConfig`
 
+<p>
+
 **类型：** `VercelImageConfig`<br/>
 **适用于：** Serverless, Static<br/>
 <Since v="3.3.0" pkg="@astrojs/vercel" />
+</p>
 
 [Vercel 的图片优化 API](https://vercel.com/docs/concepts/image-optimization) 选项。查看 [Vercel 的图片优化配置文档](https://vercel.com/docs/build-output-api/v3/configuration#images)以获取支持的参数的完整列表。
 
@@ -149,9 +154,12 @@ export default defineConfig({
 
 ### `imageService`
 
+<p>
+
 **类型：** `boolean`<br/>
 **适用于：** Serverless, Static<br/>
 <Since v="3.3.0" pkg="@astrojs/vercel" />
+</p>
 
 启用后，在生产中会自动配置并使用由 Vercel Image Optimization API 提供支持的[图像服务](/zh-cn/reference/image-service-reference/) 。在开发中，将使用由 [`devImageService`](#devimageservice) 指定的图像服务。
 
@@ -190,10 +198,13 @@ import astroLogo from '../assets/logo.png';
 
 ### `devImageService`
 
+<p>
+
 **类型：** `'sharp' | string`<br/>
-**适用于：** Serverless, Static
+**默认值：** `sharp`<br />
+**适用于：** Serverless, Static<br />
 <Since v="3.8.0" pkg="@astrojs/vercel" />
-**默认值：** `sharp`
+</p>
 
 当 [imageService](#imageservice) 启用时，允许你在开发中配置使用哪个图像服务。如果你无法在开发机器上安装 Sharp 的依赖项，但使用另一个图像服务（如 Squoosh）可以让你在开发环境中预览图像，这可能很有用。但构建不会受其影响，将始终使用 Vercel 的图像优化。
 
@@ -214,10 +225,13 @@ export default defineConfig({
 
 ### `isr`
 
+<p>
+
 **类型：** <code>boolean |   VercelISRConfig</code><br/>
-**适用于：** Serverless
+**默认值：** `false`<br/>
+**适用于：** Serverless<br/>
 <Since v="7.2.0" pkg="@astrojs/vercel" />
-**默认值：** `false`
+</p>
 
 允许你的项目作为一个 [ISR (增量式静态再生)](https://vercel.com/docs/incremental-static-regeneration) 功能部署，这个功能以首次请求后预渲染页面相同的方式缓存你按需渲染的页面。
 
@@ -286,8 +300,11 @@ export default defineConfig({
 
 ### `includeFiles`
 
+<p>
+
 **类型：** `string[]`<br/>
 **适用于：** Serverless
+</p>
 
 使用此属性来强制将文件与你的函数打包在一起。当你发现缺失文件时，这很有帮助。
 
@@ -303,7 +320,10 @@ export default defineConfig({
 });
 ```
 
+<p>
+
 ### `excludeFiles`
+</p>
 
 **类型：** `string[]`<br/>
 **适用于：** Serverless
@@ -324,8 +344,11 @@ export default defineConfig({
 
 ### `maxDuration`
 
+<p>
+
 **类型：** `number`<br/>
 **适用于：** Serverless
+</p>
 
 使用这个属性来延长或限制无服务器函数运行的最长持续时间（以秒为单位），直到超时。请参阅 [Vercel 文档](https://vercel.com/docs/functions/serverless-functions/runtimes#maxduration) 获取你的账号计划的默认和最大时限。
 
@@ -343,10 +366,12 @@ export default defineConfig({
 
 ### `skewProtection`
 
+<p>
+
 **类型：** `boolean`<br/>
 **适用于：** Serverless
 <Since pkg="@astrojs/vercel" v="7.6.0" />
-
+</p>
 使用此属性启用 [Vercel Skew protection](https://vercel.com/docs/deployments/skew-protection)（适用于 Vercel Pro 和企业账户）。
 
 ```js title="astro.config.mjs" ins={7}
@@ -380,7 +405,7 @@ export default defineConfig({
   }),
 });
 ```
-边缘中间件可以用 `ctx.locals.vercel.edge` 访问 Vercel 的 [`RequestContext`](https://vercel.com/docs/functions/edge-middleware/middleware-api#requestcontext) 。如果你正在使用 TypeScript，可以通过更新 `src/env.d.ts` 来使用 `EdgeLocals` 获得正确的类型定义：
+边缘中间件可以用 `ctx.locals.vercel.edge` 访问 Vercel 的 [`RequestContext`](https://vercel.com/docs/functions/edge-middleware/middleware-api#requestcontext) 。如果你正在使用 TypeScript，可以通过更新 `src/env.d.ts` 来使用 `EdgeLocals` [获得正确的类型定义](/zh-cn/guides/typescript/#扩展全局类型)：
 
 ```ts
 type EdgeLocals = import('@astrojs/vercel').EdgeLocals

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

@@ -139,7 +139,7 @@ export const onRequest = (context, next) => {
 };
 ```
 
-要给 `Astro.locals` 内的信息定义类型，也就是在 `.astro` 文件和中间件代码中能提供自动补全，在 `env.d.ts` 文件中声明一个全局命名空间：
+要给 `Astro.locals` 内的信息定义类型，也就是在 `.astro` 文件和中间件代码中能提供自动补全，通过在 `env.d.ts` 文件中声明一个全局命名空间来 [扩展全局类型](/zh-cn/guides/typescript/#扩展全局类型)：
 
 ```ts title="src/env.d.ts"
 type User = {

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

@@ -123,7 +123,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
 默认情况下，会话数据的类型是未被定义的，你可以将任意数据存储在任何 key 中。使用 [devalue](https://github.com/Rich-Harris/devalue) 对值进行序列化和反序列化，该库与 content layer 和 action 所使用的库相同。这意味着支持的类型是相同的，包括字符串、数字、`Date`、`Map`、`Set`、`URL`、数组和简单对象。
 
-你可以通过创建 `src/env.d.ts` 文件并为 `App.SessionData` 添加类型，来选择性地为你的会话数据定义 TypeScript 类型：
+你可以通过创建 `src/env.d.ts` 文件并为 `App.SessionData` 添加类型，来选择性地为你的会话数据 [定义 TypeScript 类型](/zh-cn/guides/typescript/#扩展全局类型)：
 
 ```ts title="src/env.d.ts"
 declare namespace App {

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

@@ -40,16 +40,6 @@ Astro 中包含三个可扩展的 `tsconfig.json` 模板：`base`、`strict` 和
 }
 ```
 
-你可以创建 `src/env.d.ts` 作为添加自定义类型声明的约定，或者如果你没有 `tsconfig.json`，则可以从 Astro 类型中受益：
-
-```ts title="src/env.d.ts"
-// 自定义类型声明
-declare var myString: string;
-
-// Astro 类型，如果你已经有 `tsconfig.json`，则不需要
-/// <reference path="../.astro/types.d.ts" />
-```
-
 ### TypeScript 编辑器插件
 
 当你不使用[官方 Astro VS Code 扩展](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode)时，可以单独安装 [Astro TypeScript 插件](https://www.npmjs.com/package/@astrojs/ts-plugin)。该插件由 VS Code 扩展自动安装和配置，你无需同时安装两者。
@@ -119,7 +109,7 @@ import type { SomeType } from "./script";
 
 ## 导入别名
 
-Astro 支持你在 `tsconfig.json` 文件里的 `paths` 配置所定义的 [导入别名](/zh-cn/guides/imports/#别名)。
+Astro 支持你在 `tsconfig.json` 文件里的 `paths` 配置所定义的导入别名。 [阅读导入指南](/zh-cn/guides/imports/#别名) 了解更多。
 
 ```astro title="src/pages/about/nate.astro" "@components" "@layouts"
 ---
@@ -139,7 +129,19 @@ import Layout from "@layouts/Layout.astro";
 }
 ```
 
-## 扩展 `window` 和 `globalThis`
+## 扩展全局类型
+
+你可以创建 `src/env.d.ts` 作为约定来添加自定义类型声明，或者在没有 `tsconfig.json` 的情况下利用 Astro 类型的优势：
+
+```ts title="src/env.d.ts"
+// 自定义类型声明
+declare var myString: string;
+
+// Astro 类型，如果你已有 `tsconfig.json` 则无需添加。
+/// <reference path="../.astro/types.d.ts" />
+```
+
+### `window` 和 `globalThis`
 
 你可能需要在全局对象中添加一项属性。可以通过在 `env.d.ts` 文件中使用 `declare` 关键字添加顶级声明来实现这一点：
 
@@ -160,6 +162,56 @@ interface Window {
 }
 ```
 
+### 添加非标准属性
+
+你可能需要为自定义属性或 CSS 属性定义类型。你可以通过在 `.d.ts` 文件中重新声明 `astroHTML.JSX` 命名空间来扩展默认的 JSX 定义，以添加非标准属性。
+
+```ts title="src/env.d.ts"
+declare namespace astroHTML.JSX {
+  interface HTMLAttributes {
+    "data-count"?: number;
+    "data-label"?: string;
+  }
+
+  // 向 style 对象添加一个 CSS 自定义属性
+  interface CSSProperties {
+    "--theme-color"?: "black" | "white";
+  }
+}
+```
+
+:::note
+`astroHTML` 会在 `.astro` 组件中全局注入。要在 TypeScript 文件中使用它，可以使用 [三斜杠指令](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html)：
+
+```ts
+/// <reference types="astro/astro-jsx" />
+
+type MyAttributes = astroHTML.JSX.ImgHTMLAttributes;
+```
+:::
+
+### 使用导入
+
+你可能希望通过复用项目中其他地方或外部库中声明的类型来扩展全局类型。为此，请使用 [动态导入](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)：
+
+```ts title="src/env.d.ts"
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+};
+
+declare namespace App {
+  interface Locals {
+    orders: Map<string, Product[]>
+    session: import("./lib/server/session").Session | null;
+    user: import("my-external-library").User;
+  }
+}
+```
+
+`.d.ts` 文件是一种 [环境模块](https://www.typescriptlang.org/docs/handbook/modules/reference.html#ambient-modules) 声明。虽然它的语法与 ES 模块类似，但这些文件不允许顶层导入/导出。如果 TypeScript 遇到一个 `.d.ts` 文件，它将被视为 [模块增强](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation)，这将破坏你的全局类型。
+
 ## 组件参数
 
 Astro 支持通过 TypeScript 来定义你的组件参数。为了启动它，你需要将一个名为 `Props` 的 TypeScript 接口添加到你的的组件。你可以（可选的）使用 `export` 语句将其导出，但这不是强制的。[Astro VS Code 扩展](/zh-cn/editor-setup/)会自动寻找 `Props` 接口，并且当你在其他模板内使用该组件时，给你提供适当的 TS 支持。
@@ -212,32 +264,6 @@ const { href, ...attrs } = Astro.props;
 </a>
 ```
 
-也可以通过在 `.d.ts` 文件中重新声明命名空间 `astroHTML.JSX`，来为默认的 JSX 定义扩展非标准属性。
-
-```ts title="src/custom-attributes.d.ts"
-declare namespace astroHTML.JSX {
-  interface HTMLAttributes {
-    "data-count"?: number;
-    "data-label"?: string;
-  }
-
-  // 添加一个 CSS 自定义属性到 style 对象中
-  interface CSSProperties {
-    "--theme-color"?: "black" | "white";
-  }
-}
-```
-
-:::note
-`astroHTML` 被全局注入到 `.astro` 组件中。如果要在 TypeScript 文件中使用它，请使用一个[三斜杠指令（triple-slash directive）](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html)来进行引用：
-
-```ts
-/// <reference types="astro/astro-jsx" />
-
-type MyAttributes = astroHTML.JSX.ImgHTMLAttributes;
-```
-:::
-
 ### `ComponentProps` 类型
 
 <p><Since v="4.3.0" /></p>