Answer
Storyblok Localization: How Translators Produce Field-Level Multilingual Content
Storyblok localization uses field-level or folder-level translation exposed via the Content Delivery API. Translators receive JSON exports or TMS connector jobs
Storyblok sits inside the broader headless-CMS localization pattern covered How App Localization Works and What Clients Are Buying, but its field-level and folder-level split changes what lands on the translator's desk. This page explains the model from the production side: what the deliverable looks like, how to price it, and where the LQA gate blocks publish.
Key points
- Storyblok is a Headless CMS with Visual Editor, built on Bloks (components) composed into Stories inside Spaces — a structure that directly shapes how translatable content is packaged and delivered to localization teams.
- Storyblok offers two localization models: field-level translation (per-locale values stored on a single Story using Dimensions) and folder-level translation (a parallel Story tree per locale folder). The content architect's choice determines whether the translator receives per-field JSON or a mirrored folder hierarchy.
- The five required translator intake artifacts are: the source content export, a translation memory (TM) for the language pair, the client term base, a locale style guide, and staging Space access via a Preview token.
- Translation is priced at $0.10–$0.25 per source word; review runs $0.04–$0.08 per source word. A mid-size program spanning five languages and 50,000 words costs Storyblok offers two localization models — field-level (Dimensions) and folder-level — and the content architect's choice decides whether the translator receives per-field JSON or a parallel Story tree.
- The translator intake maps to five artifacts: Space access, Dimensions config, Blok schema, Preview token, and Visual Editor review URL.
- Storyblok jobs are quoted by translatable-field count × Blok instances × target locales, not by page count or Story count.
- LQA runs at $40–$90 per 1,000 words against an MQM-style scorecard aligned to ISO 17100 and blocks publish on certified lanes.
- Un-translated slugs produce /es/english-slug URLs that split SEO signal — a defect LQA must catch before the locale goes live.
5,000–$75,000 depending on TM leverage, turnaround, and certification requirements.
What is Storyblok localization from the translator's side of the desk?
Storyblok localization is the field-level or folder-level translation of Blok content inside a Storyblok Space, where translatable fields are exposed per locale through the Content Delivery API's language parameter and delivered to translators as JSON exports, Translation Jobs, or TMS connector tickets rather than visual-editor edits. Translators work on externalized content, not inside the editor.
Storyblok is a headless CMS with a Visual Editor, built on Bloks (components) composed into Stories inside Spaces. The translator never authors in the Visual Editor; the editor is a review surface reached through the staging Preview token.
Three terms disambiguate the model buyers confuse most often:
| Term | What it is | When the translator meets it |
|---|---|---|
| Dimensions | Field-level locale mechanism on one Story | Flat per-field JSON deliverable |
| Folder-level | Parallel Story tree per locale (/es/, /de/) | Full Story-by-Story deliverable |
| Translate Fields app | In-editor MT seeding for post-editing | MTPE rates plus LQA still apply |
| TMS connector | Automated sync to Smartling, Lokalise, Phrase, Crowdin | Jobs appear in the agency's existing CAT environment |
Field-level or folder-level — which Storyblok localization model is the project using?
Storyblok offers two localization models — field-level and folder-level — and the content architect, not the translator, picks one. Field-level stores per-locale values on a single Story; folder-level duplicates the Story tree inside a locale folder. The choice decides the deliverable shape before the first word is translated.
flowchart TD
A[Client content architect decides] --> B{Field-level or folder-level?}
B -- Field-level --> C[Dimensions on one Story]
B -- Folder-level --> D[Parallel Story tree per locale]
C --> E[Translator receives per-field JSON diff]
D --> F[Translator receives parallel Stories]
E --> G[LQA $40–$90 per 1,000 words]
F --> G
G --> H[Publish to live locale]
The decision matrix below maps each architecture to the translator's deliverable shape and the risk class the agency must scope for:
| Setup | Deliverable shape | Risk to flag |
|---|---|---|
| Field-level (Dimensions) | Per-field JSON diff keyed by language code | Nested Bloks in richtext silently fall back |
| Folder-level | Parallel Story tree per locale folder | Blok UUID drift breaks references |
| Mixed (field-level with structural variants) | Per-field JSON plus locale-only Stories | Scope creep from un-flagged structural fields |
How does field-level translation shape the translator's deliverable?
Field-level translation stores every localizable field with per-language values on the same Story. Translators receive a JSON export or TMS job containing only the translatable fields keyed by language code (en, es, de). The Content Delivery API returns the correct value when queried with the language parameter.
The deliverable is compact. A 50-field Story in 4 locales produces 150 cells to translate (50 fields × 3 non-source locales), not 200 Stories.
How does folder-level translation shape the translator's deliverable?
Folder-level translation duplicates the Story tree inside a locale folder (/es/, /de/). Translators receive a parallel set of Stories to translate end-to-end, including Blok structure where the client has permitted structural divergence. Translators must preserve Blok UUIDs so references do not break.
This shape suits markets where the ES site diverges structurally from EN — a legal disclaimer section only shown in Germany, for example.
Which setup does Storyblok's Dimensions feature produce?
Dimensions is Storyblok's field-level mechanism, exposing locale variants on a single Story. When the Space uses Dimensions, translators work against a flat field map. When the Space uses folder-level, Dimensions is off and locale divergence is handled through folder duplication.
What does a translator receive at the start of a Storyblok localization project?
A Storyblok translator receives five artifacts mapped to the site's standard intake: the source content as a JSON export or TMS connector job, the TM for the language pair, the client's term base, the locale style guide, and Visual Editor review access via a Preview token to the staging Space. The canonical intake is explained in full Content Localization: How Translators and Agencies Produce It; the Storyblok-specific mapping is below.
| Canonical artifact | Storyblok equivalent | How it arrives |
|---|---|---|
| Source content | Space export (XLIFF, JSON) or CDN API pull | Translation Job or TMS connector |
| Translation memory | TM for the language pair | TMX file or TMS repository |
| Term base | Client glossary with Blok-field notes | TBX, CSV, or TMS term base |
| Style guide | Locale style guide plus Blok tone rules | PDF or linked doc |
| Staging access | Preview token to Visual Editor on staging Space | URL plus token header |
Missing any one of the five stalls kickoff. The Preview token is the one Storyblok-specific artifact most often forgotten; without it, LQA cannot review in context.
How is the source content exported from Storyblok?
Source content leaves Storyblok through one of three paths:
- A native Translation Job in XLIFF or JSON, created inside the Space.
- A TMS connector push to Smartling, Lokalise, Phrase, or Crowdin.
- A direct Content Delivery API pull using the language parameter against the draft version.
XLIFF and JSON file semantics are not re-explained here — see Localization Files: What Translators Receive, Parse, and Return.
What does the Blok schema tell the translator?
The Blok schema lists every component type and marks which fields are translatable. Translators consult it to confirm scope on seven field classes:
- Plain text fields
- Textarea fields
- Markdown fields
- Richtext fields (including nested Bloks)
- SEO title and SEO description
- Asset alt text
- The Story slug
Any field the client forgot to flag as translatable is a defect to raise at kickoff, not at delivery.
How does Storyblok's Content Delivery API serve localized content to the front-end?
The Content Delivery API returns a Story in the requested locale when the client passes the language parameter (?language=es) on the request, resolving to either the field-level value stored in that locale's Dimension or the folder-level Story that lives inside the matching locale folder. Translators do not call the API directly, but understanding this contract explains why the slug, SEO fields, and rich-text markdown versions must all be translated in sync — because the API assembles the response from those exact fields at request time.
What role does the language parameter play?
The language parameter on each API request selects which locale the API resolves. The language code itself is the first part of the full_slug of each language-specific Story version, and the Visual Editor requests that same path when rendering a preview — meaning the slug structure is load-bearing for both editorial review and live delivery. A missing or mismatched language parameter returns the default-language value. Untranslated fields silently fall back to the source locale — a defect the LQA gate must catch and log before publish, because it is invisible to authors working only in the default-language editor view.
Does Storyblok's GraphQL Content API change the translator's job?
The GraphQL Content API exposes the same localized fields through typed queries, so the translator's deliverables remain identical regardless of which API surface the front-end consumes. Typed GraphQL queries return the same localized fields as the REST endpoint; the practical advantage for LQA teams is that front-end engineers request only the translatable fields that are actually rendered, which narrows the LQA sample to the content that ships to end users. This reduces the volume of strings that must be scored without reducing quality coverage on the fields that matter.
Which Storyblok fields are translatable and which trip translators up?
Storyblok marks text, textarea, markdown, richtext, SEO metadata, and asset alt text as translatable when the schema flag is set. The three fields that trip translators up are the Story slug, nested Bloks inside richtext, and asset filenames referenced in markdown — each silently falls back to the default locale if missed.
| Field type | Translatable? | Common defect |
|---|---|---|
| Text / Textarea | Yes, when flagged | Flag off by default on legacy Bloks |
| Markdown | Yes | Inline asset filenames stay in source language |
| Richtext | Yes, top level only | Nested Blok fields need independent flags |
| SEO title / description | Yes | Length limits differ per locale |
| Asset alt text | Yes | Often omitted from Translation Job scope |
| Slug | Yes | Un-translated — see SEO risk below |
How should the localized slug be handled?
The slug is a localizable field in both field-level and folder-level setups. Translators localize the slug to the target language's SEO-preferred form (/es/acerca instead of /es/about), confirm the client's URL strategy, and flag any collision with existing routes. Un-translated slugs create /es/english-slug URLs that split SEO signal and confuse locale routing — the multilingual URL strategy Website Localization: What Translators and Agencies Actually Do on the Project applies directly.
What happens to nested Bloks inside a richtext field?
Richtext fields can contain nested Bloks — callouts, embeds, CTAs. Each nested Blok's text fields need the translatable flag independently. Translators returning only the top-level richtext string leave nested Blok copy in English even when the parent Story reads as fully translated.
Pricing
How do translators price and quote a Storyblok localization project?
Translators quote Storyblok work by translatable-field count × Blok instances × target locales, not by Story count. US per-word pricing applies at $0.10–$0.25 for translation and $0.04–$0.08 for review, with LQA at $40–$90 per 1,000 words as the blocking gate. A mid-size five-locale, 50,000-word Storyblok program lands at $25,000–$75,000 depending on TM leverage and certification requirements.
| Cost line | US rate | Unit |
|---|---|---|
| Translation | $0.10–$0.25 | Per source word |
| Review | $0.04–$0.08 | Per source word |
| LQA gate | $40–$90 | Per 1,000 words translated |
| 5 locales × 50,000 words | $25,000–$75,000 | Program total |
| Certified lane (e.g. USCIS) | $0.10–$0.25 per word or $25–$150 per page | Certificate of accuracy mandatory; notarization $10–$50 optional |
Why does field count beat page count for Storyblok quoting?
A Storyblok Story is composed of many Bloks, each with multiple translatable fields. A 200-Story marketing site with an average of 6 translatable fields per Story and 4 locales produces 4,800 field edits — far more than a page-count estimate implies.
The arithmetic matters because:
- Short fields (SEO title, button label) carry high per-word effort relative to length.
- Repeated Blok instances (hero, CTA) leverage TM aggressively; field count alone over-prices.
- Richtext fields with nested Bloks need per-nested-field counting to avoid under-quoting.
Where does the LQA gate sit in a Storyblok project?
LQA samples translated output at $40–$90 per 1,000 words against an MQM-style scorecard aligned to ISO 17100. It scores five dimensions:
- Accuracy
- Fluency
- Terminology
- Locale convention
- Style
LQA runs before the Story is published to the live locale in the Space. Failing it blocks publish, not just delivery.
Computer-Assisted Translation Tools: The Working Translator's Field GuideHow it works
Native Storyblok translation vs the Translate Fields app vs third-party TMS connectors — which workflow fits?
1
When does native Storyblok translation suffice?
Native translation suffices when volume is low, locales number two to three, and the agency can live with XLIFF or JSON email handoff. Beyond that threshold the manual round-trip starts dropping fields and losing version alignment.
2
What does the Translate Fields app change?
The Translate Fields app surfaces machine-translation suggestions inside the Storyblok editor for post-editing. Translators treat MT output as a draft stage — MTPE rates apply, and the LQA gate still runs at $40–$90 per 1,000 words regardless of whether MT seeded the first pass.
3
When should the project use a TMS connector?
A TMS connector suits continuous localization at scale. Storyblok pushes changed Stories to the TMS automatically. Translators work in their existing CAT environment with full TM leverage. Translated content syncs back to the correct locale on approval.
Supported connectors include:
- Smartling
- Lokalise
- Phrase
- Crowdin
What does the translator hand back, and how is it reviewed in Storyblok?
Translators hand back either the translated XLIFF or JSON file for import into the Space, or — via a TMS connector — synced field values that land directly on the target locale Dimension without a manual upload step. Native Translation Jobs support both XLIFF and JSON as round-trip export formats, giving agencies the flexibility to process files in any standards-compliant CAT tool. Review happens in Storyblok's Visual Editor using the Preview token on the staging URL, where the LQA sampler loads the content exactly as a live user would see it and scores defects against the MQM-aligned scorecard before any publish action is permitted on certified lanes.
The handback sequence runs in five steps:
- Translator uploads the translated XLIFF or JSON, or the TMS connector marks the job approved and pushes field values automatically.
- The locale fields populate on the target Story (field-level Dimension) or on the parallel folder Story (folder-level model), depending on the Space's localization architecture.
- The LQA sampler loads the Preview URL with
?language=set to the target locale, rendering the content through the same Visual Editor path that authors and developers use. - Defects — including untranslated slugs, missing SEO meta fields, and malformed rich-text — are logged against the MQM-aligned scorecard at a rate of $40–$90 per 1,000 words; failing scores block publish.
- After a passing LQA score is recorded, the Story is published to the live locale in the Space, making the translated content available through the Content Delivery API.
The Translate Fields app provides in-editor machine translation seeding for post-editing (MTPE) workflows, allowing editors to pre-populate target fields before the translator refines them — but it does not replace the LQA gate on certified lanes.
How does Storyblok localization compare to other headless CMS and page-builder platforms?
Storyblok occupies a distinct position between the pure headless CMS model and visual page builders. Like headless peers, it exposes locale-keyed content over a REST and GraphQL API, meaning the translator deliverable is structured JSON or XLIFF rather than a form-field overwrite inside a monolithic editor. Like page builders, it provides a Visual Editor that renders the assembled Blok tree in context, so reviewers can evaluate translated copy inside the actual layout rather than in an isolated string list. No other common category combines both properties in the same localization workflow.
The key structural difference for translators is that Storyblok's Blok-and-Story architecture means translatable content is scoped at the component level. A single Story can contain dozens of Blok instances, each with its own set of translatable fields — text, textarea, markdown, richtext, SEO title, SEO description, asset alt text, and localized slug — all flagged individually in the Blok schema. This per-field granularity is more surgical than a page-level export and more structured than a flat key-value JSON file, which affects both TM leverage and LQA sampling strategy.
Translation pricing reflects this complexity: at $0.10–$0.25 per source word for translation and $0.04–$0.08 per source word for review, a program spanning five languages and 50,000 words lands in the
Storyblok sits between the pure headless model and visual page builders. Like headless peers, it exposes locale-keyed content over an API; like page builders, it offers Visual Editor review. The translator deliverable is closer to locale-keyed JSON than to a per-field CMS-item overwrite. The generic headless pattern across Contentful, Strapi, and Sanity is covered CMS Localization: How Translators and Agencies Produce Multilingual Content Across Platforms and the page-builder contrast is How Webflow Localization Works and What Translators Need to Know.
5,000–$75,000 range — a figure that shifts significantly based on TM leverage, turnaround requirements, and whether the lane requires ISO 17100–aligned certification. Teams planning budgets account for LQA at $40–$90 per 1,000 words on top of translation and review costs.
How we work on Storyblok projects
We treat the architecture choice as the client's decision and the deliverable shape as a consequence of it. Before kickoff, we confirm which model the Space uses, pull the Blok schema, and quote by translatable-field count × Blok instances × target locales rather than by Story count. The intake only closes when all five artifacts are in hand — including the Preview token.
We refuse to publish a locale that has not passed LQA against the MQM-aligned scorecard. "The Translate Fields app ran MT on it" is not a substitute for the gate — MT output is a draft stage, and the $40–$90 per 1,000 words still applies on every lane, including AI-seeded ones.
We do not quietly leave the slug in English because the schema allowed it. Un-translated slugs are a defect we log and return to the client, not a cost-saving we silently ship. On certified lanes, we do not sign a certificate of accuracy on AI output; the certificate requires a human translator's sign-off, and that signature is the point of the lane.
We decline to quote a Storyblok program on page count. The arithmetic that produces 4,800 field edits from a 200-Story site is the arithmetic that keeps the budget honest, and a per-page quote hides the overage until mid-project.
Common Storyblok localization questions cover the API language parameter, slug handling, Dimensions configuration, TMS connector choice, and whether MT inside the Translate Fields app replaces LQA. The short answer on the last: it does not — LQA at $40–$90 per 1,000 words runs on every lane.
Related
- Trados as a CAT Tool: Features, Costs, and Honest Trade-offs
- Video Game Localization: What Translators and Agencies Need to Know
- Website Localization: What Translators and Agencies Actually Do on the Project
- Why Localization Is Important: The Case Translators and Agencies Make to Clients
- eLearning Localization: How Translators and Agencies Produce Multilingual Courses
- i18n Translation: How Translators Produce Localized Builds from JSON, YAML, and XLIFF