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

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

下一个网站? 使用 @bablic-io/sdk-vercel 换句话说 此软件包仅供Astro在Vercel或任何节点主机上使用.

你需要一个Bablic账户和项目。 新到巴贝利克? 报名。 。 。 .

所需资源

• 一个带有 Bablic 脚本标签的 Bablic 项目 每个 页面,服务器发送的HTML中.
• 一个婴儿 赞成 计划或免费审判。 在其他计划中,SDK服务于原始网页不变(x-moxie: skipped, (中文(简体) ), x-moxie-reason: please subscribe to pro tier)和巴布利克在浏览器中不断翻译. 计划变更后,允许约15分钟. 计划: Bablic 仪表板。 。 。 .
• 将您 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.

安装

npm install @bablic-io/sdk-astro

设置

1. 保留 Bablic 脚本标签 在您的基础布局中. is:inline 保留 Astro从捆绑它,从而到达服务器HTML.

   <script is:inline src="https://edge.bablic.com/moxie.min.js" data-oljs="P0000"></script>
   

   从您复制精确标记 Bablic 仪表板。 。 。 . 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 到达它 .

// 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时, 返回到自己的操作中:

  // 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

// 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。 。 。 .

检查它的工作原理

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数字 :

当您更改语言或 URL 时

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

如何运作

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小时). 为了更早清除他们,增加一条签名的清洗路线:

// 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 读取。 。 。 .

道德操守办公室

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那里得到他们的,有相同的链接.

// 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完成它的背景(backgroundTimeoutMs15 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"的脚本标记,包括正文页.

链接

• 婴儿
• 注册或登录
• Next.js网站: @bablic-io/sdk-vercel

许可证

麻省理工学院