ResilientLang developer documentation

ResilientLang translates a website and keeps the translations working when the vendor's servers are down. Translated text is published as static files, served from your own site and two CDNs, and applied in the visitor's browser by a small script. The product name is a placeholder.

Status of these docs. The product is being built. These pages describe the contracts and code in the repository, not a live service. There is no public endpoint yet; examples use placeholder hosts and keys. Anything we could not confirm against an official source is marked verify. See Status and open items.

Where to begin#

• Not sure which route fits your site? Read Choose a path.
• Running WordPress: WordPress quick start.
• Running Shopify: Shopify quick start.
• Any other site (Wix, Squarespace, Webflow, plain HTML, single-page apps): Script snippet quick start.
• Automating from a server or CI: API quick start and the API reference.
• Next.js, Nuxt, Astro or a static site and you want indexable translated pages: Framework and static-site SDKs.
• Putting translation in your pipeline (GitHub, GitLab, Bitbucket, Netlify, Vercel): CI/CD integrations.
• Command line and SDKs: CLI and SDKs. Events to your server: Webhooks.
• Wondering what "keeps working when your servers are down" means in practice: How resilience works.

All pages

Quick start

• Choose a path – Which integration fits your platform, and what each one can and cannot do for search engines.
• WordPress quick start – Install the plugin, enter your public keys, sync the bundles and place the switcher.
• Shopify quick start – Two delivery paths on Shopify, what each covers, and what Shopify does not let any app translate.
• Script snippet quick start – One script tag for Wix, Squarespace, Webflow, Framer, Ghost, shop platforms, plain HTML and single-page apps, with vendor-checked steps.
• API quick start – Create a site, submit strings, translate, publish and export using curl and a secret key.
• CLI and SDKs – The rl command line, the JavaScript SDK and the .NET client.
• Framework and static-site SDKs – Prerender translated pages at build time for Next.js, Nuxt, Astro and plain static HTML.
• Edge delivery – Serve translated pages on /fr/ style URLs from your own hostname at the CDN edge, for sites that cannot be prerendered at build time.
• Python, PHP and Go SDKs – Thin clients for the control-plane API in Python, PHP and Go, with the behaviour they share.
• Python SDK – Install from the repository, create a site, translate, publish and export with the Python client.
• PHP SDK – Install from the repository, bring a PSR-18 HTTP client, and manage sites, translations and publishing.
• Go SDK – A standard-library Go client with context support on every call.

CI and build tools

• CI/CD integrations – Put translation into a developer's pipeline: GitHub Action, GitLab, Bitbucket, Netlify, Vercel, a string linter and rl doctor.
• GitHub Action – Push strings, translate and publish from a workflow, and get a dry-run comment on pull requests.
• GitLab CI – Include the template, set the variables, get a preview on merge requests and a sync on the default branch.
• Bitbucket Pipelines – A pull-request preview and a main-branch sync, with secured variables.
• Netlify – A build plugin that pulls the signed bundle, prerenders translated pages and fails the build on any problem.
• Vercel – A build-step recipe for static output on Vercel.
• rl-lint – A heuristic linter for hard-coded strings and patterns the extractor cannot translate, with a pre-commit hook.
• rl doctor – A read-only check of your CLI setup, safe to run in CI.
• Troubleshooting CI runs – What each CI message means and how to fix it.

Concepts

• How resilience works – The control plane can go down; visitors still get translated pages.
• Bundle format – URL layout, manifest, language files, string keys and signatures (schema 1).
• Signing and key epochs – What is signed, how loaders and plugins verify it, and how a signing key can be replaced.
• Strings and keys – How page text becomes a string, how its key is computed, and how inline markup and variables are protected.
• The loader – Script-tag attributes, behaviour, JavaScript API and events.
• Verify a published bundle – Check a manifest signature, the site key, rollback and each language file with the Python, PHP or Go SDK.
• API keys – Site keys, secret keys, scopes, rotation and what never to do.
• SEO and the script snippet – What translating in the browser can and cannot do for search.

API

• API overview – Authentication, errors, pagination, idempotency, rate limits and scopes.
• API reference – Every operation, generated from the OpenAPI file.
• Event reference – Every webhook and platform event with its data fields and an example, generated from docs/events/EVENTS.md.
• Webhooks – Subscribe to events, verify signatures, retries and replay, and the management routes.
• Audit log – Tenant-visible, tamper-evident record of changes, with export, verification and retention.
• Team and members – Roles, invitations and member management routes (session based, not API keys).
• Verify webhooks with an SDK – One call per language that checks RL-Signature on the raw body, with a five-minute tolerance and several secrets during rotation.
• Billing – Plans, entitlements, invoices, checkout and portal routes, and how plan limits are reported as 402.
• Licensing – Licence keys, activation, offline tokens, plugin updates and what happens when a licence lapses.
• Errors – Problem types, the 402 plan and quota answers, and what to do for each.
• SDK error handling – The error object in the Python, PHP and Go SDKs, its fields, and what the 402, 403 and 503 hints mean.

Security

• Security model – What is signed, what is secret, what is verified, and what the design does not claim.
• CSP and headers – What to allow in a Content-Security-Policy and what the delivery plane sends.

Help

• Troubleshooting – Symptoms, causes and checks for the loader, the plugin and the API.
• Known limits – What the product does not do, stated plainly.
• Glossary – Terms used across these docs.
• Status and open items – What these docs are based on, and what is unverified or undecided.
• Deploy and smoke test – The offline deploy kit for a test host: secrets, validation, smoke test, health probe and readiness checklist.