@bablic-io/sdk-core

The engine behind server-side rendering for Bablic. It translates a page on the server with your Bablic project's translations and returns finished HTML in the visitor's language.

You need a Bablic account and project. New to Bablic? Sign up.

Most sites want an adapter instead:

• Next.js on Vercel: @bablic-io/sdk-vercel
• Astro: @bablic-io/sdk-astro

Use this package directly to support another host. Requires Node.js 22.

Install

npm install @bablic-io/sdk-core

Translate one page

import { MemoryCache, translateDocument } from '@bablic-io/sdk-core';

const cache = new MemoryCache();

const result = await translateDocument({
  html, // original-language HTML, including the Bablic script tag
  url: 'https://example.com/fr-fr/pricing', // the translated URL being served (example)
  cache,
});

if (result.status === 'complete') {
  // result.html: translated page
  // result.textMap: original → translated strings, for framework data
  // result.links: your project's link rules and the links that changed
} else {
  // 'skipped': not translated on the server (plan without server-side rendering, or the
  // project doesn't translate this page); serve the original.
  // 'failed': never serve or cache the result; see result.reason.
}

translateDocument reads your project from the page's Bablic script tag, translates the page on the server, and waits until translation is complete.

Serve a host: createPageHandler

The request flow the adapters share: routing, fetching the original page from the same site, translating, caching, the editor bypass and the failure rule.

import { createPageHandler, MemoryCache } from '@bablic-io/sdk-core';

const pages = createPageHandler({ project: 'P0000', cache: new MemoryCache() });

// In your request handler:
const response = await pages.handle(request); // undefined: not a translated URL

A proxy that already fetched the original page passes it in instead, and gets a response back for every request:

const response = await pages.translateHtml({ request, html, status, headers });

Same routing, cache, editor bypass and failure rule as handle; the original is never fetched again, not even for background refreshes. A URL that isn't translated, or a page already translated on the server (x-moxie header, or <html data-moxie-mode="ssr">), comes back unchanged with x-moxie: pass and the reason.

For a URL that isn't translated, await pages.explain(request) says why (for example, which language folders the project has), for an x-moxie-reason header or a log line.

project is your Bablic project key. Translated URLs come from your Bablic dashboard settings (language folders or subdomains); projectResolver and routeFromConfig expose that routing on its own.

Options match the adapters (project, resolve, pageTtl, timeoutMs, cache, moxie, editorCookie, onResult, onUnsupported, host, fetch), plus host hooks: buildId, sourceHeaders, ignoreParams, dropRequestHeaders, transformHtml and absoluteRedirects. See the @bablic-io/sdk-vercel README for behavior, response headers and hosting rules.

Other exports

• CacheStore: the cache interface (get, set with ttl and tags, expireTag). MemoryCache implements it.
• createRevalidateHandler({ secret, cache }): signed purge endpoint that clears cached pages, or the cached project config with {"config": true}.
• rewriteHref(href, rules), localizeHref(href, links): apply your project's link rules to a URL, as Bablic does in the page.
• projectResolver({ project, cache }), routeFromConfig(config, url): your project's translated URLs.
• isCrawler(userAgent), isStagingUrl(url).

Links

• Bablic
• Sign up or log in

License

MIT