Bablic server-side translation for sites behind Cloudflare

This guide describes how to set up Bablic server-side translation for a server-rendered website (Drupal, WordPress or another CMS) whose traffic is served through Cloudflare. Once it is in place, translated pages are delivered to visitors and search engines already translated. The original language is never displayed first, and every language version of a page can be indexed.

The setup runs entirely on your infrastructure and uses two npm packages from Bablic:

• @bablic-io/sdk-node: Bablic’s translation service, installed on a server running Node.js.
• @bablic-io/sdk-cloudflare: a Cloudflare Worker that sends your translated pages through that service and caches the results at the edge.

Apart from adding the Bablic script tag, no changes to your site’s code are required.

visitor ──► Cloudflare Worker ──► your origin (original page)
                  │   ▲
                  ▼   │
     Bablic's translation service (@bablic-io/sdk-node)

Summary

Bablic’s side

Your side

For assistance at any step, contact support@bablic.com.

Before you start

• A Bablic account and project (sign up), with steps B1 to B4 done.
• Your site behind Cloudflare (the DNS record for your hostname is proxied, the orange cloud), and permission to create Workers and routes on the zone. A server for the translation service:
  • Node.js 22.19 or later;
  • reachable from the internet over HTTPS;
  • able to make outbound HTTPS requests to https://edge.bablic.com. It can be the same machine as your website or a separate one.
• Node.js 22 on the workstation used to deploy the Worker.

Replace the following placeholders in the examples with your own values:

Step 1: Add the Bablic script tag to every page

The tag must be in the HTML your server sends, on every page. A tag inserted later in the browser, for example by a tag manager, is not visible to the translation service.

Copy the exact tag from the Bablic dashboard (Installation & Deployment). It has this form:

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

Drupal: add it inside <head> in your front-end theme’s html.html.twig (if the template is not present, copy it from the base theme into your theme), then rebuild caches:

drush cr

Other CMSs: add it to the shared page template or <head> include.

Then purge Cloudflare’s cache for your HTML pages (Caching → Configuration → Purge Cache), so cached pages pick up the tag.

Check:

curl -s https://www.example.com/ | grep -o '<script[^>]*data-oljs[^>]*>'

Step 2: Allow Bablic in your Content Security Policy

If your site sends a Content-Security-Policy header, the browser part of Bablic must be allowed to load and call home. It translates content that appears after the page loads (menus, AJAX results, pop-ups) and pages for signed-in visitors.

Add https://edge.bablic.com to:

• script-src (or script-src-elem), unless it already allows all hosts;
• connect-src.

Check: open a translated page in your browser and look in the developer-tools console. There should be no “Refused to connect” or “Refused to load” errors that mention a Bablic host. If another Bablic host appears there, add it the same way.

Step 3: Run Bablic’s translation service (@bablic-io/sdk-node)

3a. Install and start it

On your server:

mkdir -p /opt/bablic && cd /opt/bablic
npm init -y
npm install @bablic-io/sdk-node
BABLIC_LISTEN=0.0.0.0 ./node_modules/.bin/bablic-node serve
# bablic-node listening on 0.0.0.0:8790

The translation service stores no project settings. Each request carries your project key; all other settings are read from your Bablic project.

3b. Keep it running (systemd example)

/etc/systemd/system/bablic-node.service:

[Unit]
Description=Bablic translation service
After=network-online.target

[Service]
WorkingDirectory=/opt/bablic
ExecStart=/usr/bin/env node /opt/bablic/node_modules/@bablic-io/sdk-node/dist/cli.js serve
Environment=BABLIC_LISTEN=127.0.0.1
Environment=BABLIC_PORT=8790
Restart=always
User=nobody

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now bablic-node

Docker: a Dockerfile is provided in the @bablic-io/sdk-node README.

3c. Put HTTPS in front of it

Cloudflare reaches the service over HTTPS. Example with nginx on the same server (the service listens on 127.0.0.1:8790):

server {
    listen 443 ssl;
    server_name translate.example.com;
    # ssl_certificate / ssl_certificate_key: your certificate

    client_max_body_size 6m;          # pages up to 5 MB (BABLIC_MAX_BODY_MB)
    location / {
        proxy_pass http://127.0.0.1:8790;
        proxy_read_timeout 30s;
    }
}

The hostname can sit on Cloudflare too (proxied DNS record), or be served directly from the server.

3d. Check it

curl -s https://translate.example.com/healthz
# {"ok":true,"edge":"ok","projects":0}

Then translate one page by hand. Fetch an original page and ask for its translated URL:

curl -s https://www.example.com/about > /tmp/page.html
curl -s -D - -o /tmp/translated.html https://translate.example.com/translate \
  -H 'x-bablic-project: P0000' \
  -H 'x-bablic-url: https://www.example.com/<language-folder>/about' \
  -H 'content-type: text/html' \
  --data-binary @/tmp/page.html | grep -i -E '^HTTP|x-moxie'

Expect x-moxie: MISS the first time and HIT on a repeat. /tmp/translated.html holds the translated page.

Main settings

Full list: the @bablic-io/sdk-node README.

Step 4: Create and deploy the Cloudflare Worker (@bablic-io/sdk-cloudflare)

4a. Generate the Worker project

On any machine with Node.js 22:

npx @bablic-io/sdk-cloudflare init bablic-worker \
  --project P0000 \
  --engine https://translate.example.com \
  --bypass-cookies 'SESS,SSESS' \
  --route 'www.example.com/*' --zone example.com
cd bablic-worker
npm install

This writes three files:

• wrangler.toml: the Worker’s settings, route and the nodejs_compat flag;
• package.json;
• src/index.js: the Worker’s entry point.

Any option can be omitted and set in wrangler.toml afterwards.

--bypass-cookies names the session cookies of signed-in visitors. Their pages are personalized, so the Worker neither translates nor caches them; Bablic translates them in the browser instead.

4b. Deploy

npx wrangler login      # first time only; opens Cloudflare in your browser
npx wrangler deploy

4c. Routes

• Language folders: the route www.example.com/* covers everything. The Worker forwards requests for untranslated pages directly to your origin. To have the Worker run only on translated pages, use one route per language folder instead, e.g. www.example.com/<language-folder>/*.
• Language subdomains: add a route for each language hostname, e.g. <language>.example.com/*, and make sure each subdomain has a proxied DNS record pointing at your origin.

Routes can also be managed in the Cloudflare dashboard: Workers & Pages → bablic-translate → Settings → Domains & Routes.

4d. Settings

These are [vars] in wrangler.toml, or Settings → Variables in the Cloudflare dashboard. Run npx wrangler deploy again after changing wrangler.toml.

Step 5: Test

5a. Response headers

curl -sI <your-translated-url> | grep -i -E 'x-bablic-edge|x-moxie'
curl -sI <your-translated-url> | grep -i -E 'x-bablic-edge|x-moxie'

Untranslated pages carry no x-bablic-edge header, because the Worker forwards them directly to your origin.

5b. The page itself

curl -s <your-translated-url> | grep -o -E '<html[^>]*>|<link[^>]*hreflang[^>]*>' | head

• <html lang="…"> has the page’s language, and data-moxie-mode="ssr".
• hreflang links list every language.
• In the browser’s View Source, the page text is already translated. This is the version search engines index.
• Links on the page stay inside the language folder or subdomain.

5c. Signed-in visitors and Bablic Studio

Sign in to your site, then open a translated page:

curl -sI -H 'cookie: SESSexample=1' <your-translated-url> | grep -i -E 'x-bablic-edge|cache-control'
# x-bablic-edge: bypass
# cache-control: private, no-store

In the browser, the page is still displayed translated: Bablic translates it on the page. Bablic Studio works on translated pages as before.

5d. Dynamic content

On a translated page, use a pager, a filter, search suggestions or a pop-up. Content that appears after the page loads is translated by Bablic in the browser.

Debugging

Start from the response headers of a translated URL:

curl -sI <your-translated-url> | grep -i -E 'x-bablic-edge|x-moxie'

Whenever a page is not translated, the x-moxie-reason header gives a one-line explanation.

Useful commands

# Translation service logs (systemd)
journalctl -u bablic-node -f

# Worker logs, live
npx wrangler tail

# Translation service metrics, on the server itself
curl -s http://127.0.0.1:8791/metrics | grep bablic_pages_total

Keeping it up to date

Update both packages when Bablic releases a new version:

# Translation service
cd /opt/bablic && npm install @bablic-io/sdk-node@latest && sudo systemctl restart bablic-node

# Worker
cd bablic-worker && npm install @bablic-io/sdk-cloudflare@latest && npx wrangler deploy

Contact

Bablic support: support@bablic.com. Please include:

• your project key;
• a translated URL;
• the output of curl -sI <your-translated-url>.