How to Integrate Lokalise with Your Headless CMS

What is Lokalise?

Lokalise is a translation and localization platform used by product, marketing, design, and localization teams to manage multilingual text across websites, apps, games, and software products. It provides translation projects, keys, files, branching, tasks, translation memory, machine translation, screenshots, and APIs for syncing copy between development tools and localization workflows. Teams use Lokalise when translated strings need to stay connected to product releases instead of living in spreadsheets, email threads, or one-off JSON files.

Why integrate Lokalise with a headless CMS?

Localization gets messy when your source content lives in one place, your translators work in another, and your engineering team has to copy JSON files by hand before every release. A single product page can include a title, slug, SEO description, feature bullets, legal disclaimers, image alt text, and linked product specs. If only 6 of those 20 fields need translation, sending the whole document to a translation tool creates extra cost, extra review work, and more chances to overwrite fields that shouldn't change.

Architecture overview

A typical Sanity and Lokalise integration starts when content is published or updated in Sanity Studio. A Sanity webhook can trigger on publish events, or a Sanity Function can run server-side logic directly in response to a content mutation. The handler receives the document ID, uses @sanity/client to query the Content Lake with GROQ, and selects only fields that should be translated, such as title, slug.current, excerpt, body blocks, SEO fields, and image alt text. References can be joined in the same GROQ query, so a product page can include referenced category names or feature labels without making several API calls. The handler then maps those fields into Lokalise-friendly JSON, base64-encodes the file payload, and calls Lokalise's Files API through @lokalise/node-api to upload it into a project with a source language such as en. Translators and reviewers work in Lokalise using tasks, translation memory, screenshots, and status workflows. Once translations are ready, you can pull completed files back from Lokalise on a schedule, through a release script, or through a Lokalise webhook, then write localized fields back into Sanity or serve locale-specific files from your app. The end user only sees the final localized experience, but the source content, translation status, and delivery pipeline stay connected.

Common use cases

Step-by-step integration

1. 1

   Set up Lokalise access

   Create or open a Lokalise project, note the project ID from the project settings, and create an API token from your Lokalise profile. Install the Node SDK with npm install @lokalise/node-api.

2. 2

   Model localized content in Sanity Studio

   Add clear translatable fields to your schema, such as title, excerpt, body, seoTitle, seoDescription, and image alt. Keep operational fields, such as SKU, product ID, price, and publish date, separate so they aren't sent for translation.

3. 3

   Create the publish trigger

   Use a Sanity webhook filtered to the document types you translate, or use a Sanity Function if you want server-side processing without running a separate endpoint. Include the document ID and dataset in the payload.

4. 4

   Fetch exactly what Lokalise needs

   In the handler, use @sanity/client and GROQ to fetch the published document. Project only the fields Lokalise should receive, and flatten Portable Text or nested fields into JSON keys your localization team can recognize.

5. 5

   Push source strings into Lokalise

   Use @lokalise/node-api to call the Files API upload endpoint. Send a base64-encoded JSON file, set lang_iso to your source language, and choose a filename pattern such as sanity.article.<documentId>.en.json.

6. 6

   Test the localized experience

   Publish one test document, confirm the keys appear in Lokalise, translate one target locale, and verify your frontend renders the translated title, body, slug, and SEO fields for that locale.

How Sanity + Lokalise works

CMS approaches to Lokalise

Keep building

Explore related integrations to complete your content stack.