# @bablic-io/sdk-astro 中文文档

规范地址：https://npmcn.com/package/%40bablic-io/sdk-astro/

版本：1\.4\.0
npm 元数据更新时间：2026-11-05T18:31:16.045Z
中文译文更新时间：2026-11-09T22:04:40.282Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bablic-io/sdk-astro
原文对照：https://npmcn.com/package/%40bablic-io/sdk-astro/?lang=original
项目主页：https://www.bablic.com/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：80 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：astro \>=5\.0\.0
- 首次发布：2026-10-13T17:55:04.119Z
- 最新版本发布：2026-11-05T18:31:15.855Z
- 近 30 天下载量：1710（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

用 Bablic 翻译您的 Astro 站点: 服务器发送, 各种语言的 SEO 可索引页面 .

## 安装

```sh
npm install @bablic-io/sdk-astro
```

也可以使用：`pnpm add @bablic-io/sdk-astro`、`yarn add @bablic-io/sdk-astro`、`bun add @bablic-io/sdk-astro`

## README

# @bablic-io/sdk-astro (英语)

服务器端渲染 [婴儿](https://www.bablic.com/) 在阿斯特罗。 您的翻译页面在服务器上被渲染, 因此访问者和搜索引擎收到完成的, 可用其语言索引的 HTML 。 在浏览器中,Bablic继续翻译后来出现的内容. 建于 Astro 6 开通 `@astrojs/vercel`; 与任何节点适配器合作.

**下一个网站?** 使用 [`@bablic-io/sdk-vercel`](https://www.npmjs.com/package/@bablic-io/sdk-vercel) 换句话说 此软件包仅供Astro在Vercel或任何节点主机上使用.

你需要一个Bablic账户和项目。 新到巴贝利克? [报名](https://dashboard.bablic.com/)。 。 。 .

## 所需资源

-   一个带有 Bablic 脚本标签的 Bablic 项目 **每个** 页面,服务器发送的HTML中.
-   一个婴儿 **赞成** 计划或免费审判。 在其他计划中,SDK服务于原始网页不变(`x-moxie: skipped`, (中文(简体) ), `x-moxie-reason: please subscribe to pro tier`)和巴布利克在浏览器中不断翻译. 计划变更后,允许约15分钟. 计划: [Bablic 仪表板](https://dashboard.bablic.com/)。 。 。 .
-   将您 Bablic 仪表板中设置的 URL 翻译为语言 **文件夹** (例如 `example.com/fr-fr/…`),或语言 **子域** 根据要求提供的网站。 Cookie和查询参数设置没有单独的每个语言的URL,因此它们只在浏览器中继续翻译:SDK服务于他们的页面不变(SDK)`x-moxie: skipped`),即使有习惯 `resolve`。 。 。 .
-   仪表盘文件夹必须是您想要的路径 : 文件夹 `/fr-fr/` 服务 `/fr-fr/…`永远 `/fr/…`。 。 。 .
-   带节点适配器的Astro 6(`@astrojs/vercel` 10或后起于凡尔赛.
-   节点.js 22.

## 安装

```sh
npm install @bablic-io/sdk-astro
```

## 设置

1.  **保留 Bablic 脚本标签** 在您的基础布局中. `is:inline` 保留 Astro从捆绑它,从而到达服务器HTML.
    
    ```astro
    <script is:inline src="https://edge.bablic.com/moxie.min.js" data-oljs="P0000"></script>
    ```
    
    从您复制精确标记 [Bablic 仪表板](https://dashboard.bablic.com/)。 。 。 . `P0000` 代表您的工程密钥 。 不要从客户端代码或标签管理器中添加标签.
    
    添加 `data-glweb-opacity="1"` 到标签。 没有它,Bablic脚本就隐藏了每个原始语言的页面(接近零不透明),直到其设置到达,这需要第一次油漆和灯塔分数. 由SDK服务而翻译的页面从不隐藏;SDK将这个属性设置在它们上. 标签也可以装入 `defer`保留 `P` 开始时 `data-oljs`。 。 。 .
    
2.  **添加路由或中间软件** 使用您的工程密钥, 取决于您的页面渲染方式( 下面) 。 SDK从您的 Bablic 仪表板设置中读取了您翻译过的URL,所以您不会在代码中列出语言或URL.
    
3.  **有部署保护的 Vercel 预览部署 :** 打开 **设置-部署保护**打开 **自动化保护副通道**,然后重新部署。 没有它,SDK对每个原始页面的获取就会被发送到Vercel登录,并且没有翻译页面. SDK发送秘密 Vercel 提供(`VERCEL_AUTOMATION_BYPASS_SECRET`) 独活.
    
4.  **预览域 :** 仅针对您工程允许的域的 Bablic 答案, 每个域设置链接规则 。 在仪表盘中添加预览域作为您的项目的中转域 。 使用分支的稳定域( E)`<project>-git-<branch>-<team>.vercel.app`)或自定义预览域名,因为每次部署都会自有URL变化.
    

### 首页 : `moxieRoute`

`@astrojs/vercel` 仅在构建时运行预发页面的中端软件,因此添加一个点播的call-all路由. 您的预发页面优先; 只有没有页面的 URL 到达它 .

```ts
// src/pages/[...path].ts
import { moxieRoute } from '@bablic-io/sdk-astro';

export const prerender = false;
export const GET = moxieRoute({ project: 'P0000' });
export const HEAD = GET;
```

翻译的 URL 已送达翻译 。 任何其他到达路线的 URL 得到404,因为它会没有它 `x-moxie: none` 还有一个 `x-moxie-reason` 说为什么.

-   **删除语言文件夹下的预发页面.** 例如: `src/pages/fr/index.astro` 所以SDK从不看 `/fr/`。保留每页一份,以原文写出.
    
-   **使用语言文件夹** 与这个设置。 一个语言子域与您预发的页面共享其路径, 因此该路径从未看到这些请求 .
    
-   **根部已经有一条通通的路线了吗?** 打电话 `moxieRoute` 当它返回404时, 返回到自己的操作中:
    
    ```ts
    // src/pages/[...path].ts
    import type { APIRoute } from 'astro';
    import { moxieRoute } from '@bablic-io/sdk-astro';
    
    export const prerender = false;
    const bablic = moxieRoute({ project: 'P0000' });
    
    export const GET: APIRoute = async (context) => {
      const translated = await bablic(context);
      if (translated.status !== 404 || translated.headers.get('x-moxie') !== 'none')
        return translated;
      return yourHandler(context); // your existing catch-all logic
    };
    export const HEAD = GET;
    ```
    
-   **边缘中间软件继续工作.** 与 `middlewareMode: 'edge'`,您的中间软件在翻译 URL 的路径之前运行,并在 SDK 获取原始页面时再次运行,所以您的重定向和状态代码(410,404)也适用于翻译 URL 。 仅 `moxieMiddleware` 需要节点运行时间.
    

### 点播页面: `moxieMiddleware`

```ts
// src/middleware.ts
import { sequence } from 'astro:middleware';
import { moxieMiddleware } from '@bablic-io/sdk-astro';

export const onRequest = sequence(moxieMiddleware({ project: 'P0000' }) /*, your middleware */);
```

它跳过预发页面,并支持语言文件夹和子域. 它运行的 Bablic 在你的中间软件, 所以它需要节点.js运行时间: 不要结合它与 `middlewareMode: 'edge'`。对于边缘中间软件,使用 `moxieRoute`。 。 。 .

## 检查它的工作原理

```sh
curl -sI https://<your-translated-url>        # x-moxie: MISS, then HIT on a second request
```

在被保护的Vercel预览上,添加绕行密件: `curl -sI -H "x-vercel-protection-bypass: <secret>" https://<your-translated-url>`。 。 。 .

查看页面来源 : `<html … data-moxie-mode="ssr">` 和一个 `<script type="application/json" id="moxie-manifest">`。 。 。 .

当您的项目在 Stage 时, 添加 `?bablic_preview=1` 转到 URL。 恒定响应永远不会被缓存.

SDK手柄的每一个反应 `x-moxie`; 除外 `HIT`, (中文(简体) ), `STALE`, (中文(简体) ), `MISS` 财务报告和审定财务报表 `bypass` 还携带 `x-moxie-reason`数字 :

| `x-moxie` | 含义 |
| --- | --- |
| `HIT` | 从缓存服务. |
| `STALE` | 从缓存中服务, 并在背景中准备新的翻译 . |
| `MISS` | 为这个请求翻译,然后被缓存 . |
| `none` | 不是翻译的 URL (404). 原因列出SDK所看到的文件夹及其配置的年代,或为何配置无法被读取. |
| `redirect` | 原页重定向; `Location` 遵循您的链接规则。 原因显示了两个URL. |
| `pass` | 原始页面不是200 HTML 页面(404,410,JSON.);服务至今. |
| `skipped` | 未在服务器上翻译:您的计划不包含它,或者项目不翻译此页面(没有直播,没有脚本标记,或者翻译关闭). |
| `failed` | 翻译失败;在失败规则下提供了原始页面. |
| `bypass` | Bablic编辑器的要求;原页,未刻. |

## 当您更改语言或 URL 时

SDK从 Bablic 读取您的工程设置,并缓存5分钟; Bablic 自己的缓存加起来可达 10. 仪表板的改变在大约15分钟内到达了SDK,没有代码的改变或重新部署. `x-moxie-reason` 404上显示SDK目前看到的文件夹。 早点把SDK的拷贝放下 POST `{"config": true}` 到重新验证的路由([清除缓存](https://npmcn.com/package/%40bablic-io/sdk-astro/#readme-clearing-the-cache)) (中文(简体) ).

## 如何运作

1.  要求翻译的 URL 到达路由或中间软件 。 立即提供缓存翻译(`x-moxie: HIT`) (中文(简体) ).
2.  失选时, SDK 从相同的部署中获取原始页面( 对于一个语言文件夹, 没有文件夹的同一路径; CDN 服务预发页面) , 并用您的工程翻译在服务器上翻译 .
3.  翻译的页面被缓存并服务(`x-moxie: MISS`) (中文(简体) ).
4.  在浏览器中,"Bablic"脚本会翻译后加的内容,包括"岛屿"的文本("Bablic")`client:*`)渲染,而不重做服务器的工作.

链接和重定向遵循您在 Bablic 的项目链接规则, 因为请求所在域域 。 SDK从不发明URL:没有规则,链接保持不变. 翻译版的 `<html lang>` 是来自您仪表板的语言代码(除非您的项目设置了自己的HTML语言),所以浏览器不会提供再次翻译它的机会. 已翻译的 URL 将原始路径保存在语言文件夹下 (`/fr-fr/pricing`);被翻译的流涕还没有支持.

如果翻译失败或时间已出, 则不提供部分服务或缓存: 搜索引擎获取 `503`,访问者获得原始页面 `noindex`。 。 。 .

## 清除缓存

页面在之后自己刷新 `pageTtl` (1小时). 为了更早清除他们,增加一条签名的清洗路线:

```ts
// src/pages/api/bablic/revalidate.ts
import type { APIRoute } from 'astro';
import { createRevalidateHandler, runtimeCache } from '@bablic-io/sdk-astro';

export const prerender = false;
const revalidate = createRevalidateHandler({
  secret: import.meta.env.MOXIE_REVALIDATE_SECRET,
  cache: runtimeCache(),
});
export const POST: APIRoute = ({ request }) => revalidate(request);
```

邮政 `{"tkey":"<translation key>"}` (编) `"url_hashes": [...]` 单页),或 `{"config": true}` 以页眉重读您的工程设置 `x-moxie-signature: sha256=<hex HMAC-SHA256 of the body, keyed with the secret>`。 。 。 .

## 选项

`project`, (中文(简体) ), `pageTtl`, (中文(简体) ), `staleTtl`, (中文(简体) ), `timeoutMs`, (中文(简体) ), `backgroundTimeoutMs`, (中文(简体) ), `cache`, (中文(简体) ), `editorCookie`, (中文(简体) ), `onResult`, (中文(简体) ), `onUnsupported`, (中文(简体) ), `resolve`, (中文(简体) ), `moxie`, (中文(简体) ), `host`, (中文(简体) ), `fetch`附加时 `buildId` 财务报告和审定财务报表 `sourceHeaders`默认值在 [`@bablic-io/sdk-vercel` 读取](https://www.npmjs.com/package/@bablic-io/sdk-vercel)。 。 。 .

## 道德操守办公室

SDK在每个翻译页面上所做的:

-   `<html lang>` 编辑 `content-language` 标头从您的仪表板上携带语言代码,作为BCP-47标签(`fr-FR`) (中文(简体) ).
-   一个犬人, `og:url` 或者说 `twitter:url` ,将原始页面的名称指向已翻译的URL,所以每种语言都是自己的页面,而不是重复。 一个叫别页的单词.
-   标题、描述、开放图和Twitter标签、JSON-LD和图像 `alt` 文本与其余页面一起翻译.
-   JSON-LD(结构数据)在被翻译页面的点: `url`, (中文(简体) ), `item`, (中文(简体) ), `mainEntityOfPage` 财务报告和审定财务报表 `@id` 为您网站的一页命名的值获得翻译的 URL,以及 `inLanguage` 页面的语言。 全站节点,其 `@id` 是您的主页加一 `#` 名称( e)`#organization`, (中文(简体) ), `#website`),每页都保持不变. 文件和其他站点的URL被单独保留.
-   hreflang值是有效的BCP-47标记. 西班牙语( Universal)等具有私用区域的语言代码 `ES-XM`,写入 `es`中,在hreflang语中和 `og:locale`,因为搜索引擎忽略了一个不存在的区域.

你的项目和网站决定是什么:

-   **红花.** Bablic 为每种语言添加替代语 `x-default` 当为您的工程启用 hreflang 时( ask Bablic support) , 并仅在没有hreflang 标记的页面上翻译。 您的原始语言页面需要相同的设定,而预发页面从不通过SDK,所以在下面添加构建步骤. 不要自己打印hreflang标签:一个部分集(只打印) `en` 财务报告和审定财务报表 `x-default`阻止Bablic 添加其余部分.

### 原始页面上的hreflang

`bablicHreflang` 在网站建立时, 从您在 Bablic 仪表板上的项目语言中将 hreflang 设定写入每个预发页面 。 翻译的网页仍然从Bablic那里得到他们的,有相同的链接.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';
import { bablicHreflang } from '@bablic-io/sdk-astro';

export default defineConfig({
  site: 'https://<your-domain>', // the links' origin
  adapter: vercel(),
  integrations: [bablicHreflang({ project: 'P0000' })],
});
```

-   在仪表盘中添加或去除语言后重建. 构建日志显示有多少页面有链接.
-   它跟着你 `trailingSlash` 设置( c)`/fr` 或者说 `/fr/` 语言主页).
-   页面在没有巴布利克脚本标记、有自己的克勒弗朗标记、是 `noindex`,有条条可指定另一页,或者坐在语言文件夹下。 404页和500页.
-   如果工程配置无法被读取,则会在没有链接的情况下继续构建,并记录一个警告.
-   **闪烁.** SDK不会改变你的网站地图的 使用您的站点映射工具添加每种语言的 URL( 您的原始路径) .
-   **图像.** `og:image` 其他图像作为您的站点设置, 除非您的工程翻译图像 .
-   **链接.** 链接遵循您工程的链接规则为页面服务域. 没有规则的域保留了原始链接,因此为您的生产域以及任何中程或预览域设置了规则 .

## 缓存和速度

-   **新鲜** 页:1 `pageTtl` (1小时):从缓存送达(`x-moxie: HIT`) (中文(简体) ).
-   **施特尔** 在此之后,或在新部署之后:仍一次服役(`x-moxie: STALE`),并在背景中刷新. 部署后,一个HTML原文不变的页面会保留其翻译(一次取出正本,没有新译出). 过期的页面总是被再次翻译, 因此在 Bablic 中编辑显示在其中 `pageTtl`。 。 。 .
-   **固定状态** 页:1 `staleTtl` 期满后(7天);只有一页没有长篇的译出,而游客则等待.
-   **慢第一个翻译 :** 如果第一页的翻译经过 `timeoutMs`,访问者得到失败规则 和SDK完成它的背景(`backgroundTimeoutMs`15 s),所以下一个访客得到一个 `HIT`。 。 。 .
-   **温暖:** 在部署后请求每个已翻译的 URL( 无) `?bablic_preview=1`在访客到达前填充缓存.
-   **`Server-Timing`** 例如,每个答复都显示时间走向 `mx;desc="MISS", cache;dur=3, source;dur=42, translate;dur=870, total;dur=918`. 浏览器 Dev 工具和灯塔显示.

## 托管规则

-   关闭您翻译的 URL 的 ISR 。 ISR忽略了cookie,因此可以缓存Stage和编辑回复.
-   您站点前的 CDN 不得缓存 HTML 请求 `opemoxieoverride` 饼干.
-   每页都保留"Bablic"的脚本标记,包括正文页.

## 链接

-   [婴儿](https://www.bablic.com/)
-   [注册或登录](https://dashboard.bablic.com/)
-   Next.js网站: [`@bablic-io/sdk-vercel`](https://www.npmjs.com/package/@bablic-io/sdk-vercel)

## 许可证

麻省理工学院

## 常见问题

### @bablic-io/sdk-astro 是什么？

用 Bablic 翻译您的 Astro 站点: 服务器发送, 各种语言的 SEO 可索引页面 \.

### 如何安装 @bablic-io/sdk-astro？

在项目目录运行 npm install @bablic-io/sdk-astro，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：astro（\>=5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bablic-io/sdk-astro 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bablic-io/sdk-astro 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bablic-io/sdk-astro 可以商用吗？

@bablic-io/sdk-astro 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bablic-io/sdk-astro 的下载量有多少？

根据 npm 官方下载统计，@bablic-io/sdk-astro 在 2026/10/08 – 2026/11/06 这 30 天内被下载 1,710 次，日均约 57 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bablic-io/sdk-astro 还在维护吗？

最新版本 1\.4\.0 发布于 2026/11/06（4 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/10/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。