OnlineDocTranslatorGuides

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.

  • LQA runs at $40–$90 per 1,000 words against an MQM-style scorecard aligned to ISO 17100 and blocks publish on certified lanes.
  • Native Translation Jobs export as XLIFF or JSON for round-trip handoff; TMS connectors for platforms such as Smartling, Lokalise, Phrase, and Crowdin support continuous localization at scale.
  • Un-translated slugs produce locale-prefixed URLs that carry the source-language slug — a defect that splits SEO signal and must be caught by LQA before the locale goes live.
  • 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:

    TermWhat it isWhen the translator meets it
    DimensionsField-level locale mechanism on one StoryFlat per-field JSON deliverable
    Folder-levelParallel Story tree per locale (/es/, /de/)Full Story-by-Story deliverable
    Translate Fields appIn-editor MT seeding for post-editingMTPE rates plus LQA still apply
    TMS connectorAutomated sync to Smartling, Lokalise, Phrase, CrowdinJobs 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:

    SetupDeliverable shapeRisk to flag
    Field-level (Dimensions)Per-field JSON diff keyed by language codeNested Bloks in richtext silently fall back
    Folder-levelParallel Story tree per locale folderBlok UUID drift breaks references
    Mixed (field-level with structural variants)Per-field JSON plus locale-only StoriesScope 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 artifactStoryblok equivalentHow it arrives
    Source contentSpace export (XLIFF, JSON) or CDN API pullTranslation Job or TMS connector
    Translation memoryTM for the language pairTMX file or TMS repository
    Term baseClient glossary with Blok-field notesTBX, CSV, or TMS term base
    Style guideLocale style guide plus Blok tone rulesPDF or linked doc
    Staging accessPreview token to Visual Editor on staging SpaceURL 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:

    1. A native Translation Job in XLIFF or JSON, created inside the Space.
    2. A TMS connector push to Smartling, Lokalise, Phrase, or Crowdin.
    3. 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 typeTranslatable?Common defect
    Text / TextareaYes, when flaggedFlag off by default on legacy Bloks
    MarkdownYesInline asset filenames stay in source language
    RichtextYes, top level onlyNested Blok fields need independent flags
    SEO title / descriptionYesLength limits differ per locale
    Asset alt textYesOften omitted from Translation Job scope
    SlugYesUn-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 lineUS rateUnit
    Translation$0.10–$0.25Per source word
    Review$0.04–$0.08Per source word
    LQA gate$40–$90Per 1,000 words translated
    5 locales × 50,000 words$25,000–$75,000Program total
    Certified lane (e.g. USCIS)$0.10–$0.25 per word or $25–$150 per pageCertificate 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:

    1. Accuracy
    2. Fluency
    3. Terminology
    4. Locale convention
    5. 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 Guide

    How 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:

    1. Translator uploads the translated XLIFF or JSON, or the TMS connector marks the job approved and pushes field values automatically.
    2. 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.
    3. 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.
    4. 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.
    5. 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