How do you translate and publish structured content without breaking the content model?

Last reviewed: September 20, 2026

What content-model decisions make structured content translatable and publishable?

Treat structured content localization as five modeling decisions, made once per content type and reused for every entry that flows through it:

• Translatable-field map: For each content type, mark every field as translate, copy source, or do not translate. Smartling's Contentful (Fields) connector exposes exactly these choices per field — Copy source delivers the latest source value into the target field on every delivery (useful for SKUs and image URLs), and Do not translate leaves a field for locale-specific handling inside the CMS, such as a JSON field holding GPS coordinates or an application URL. A field with no parsing configuration is not captured at all, so an unmapped field is a silent gap, not a default.
• Parsing method per field: Choose how each translatable field is segmented — Plain text, Markdown, HTML, Rich Text (for native rich-text fields), or ICU for plural-sensitive strings. Smartling's connector documentation ties HTML and Markdown parsing directly to translator experience and translation-memory leverage, because sentence-level strings match previous translations more often than one field-sized block does.
• Reference strategy: For entry-level and document-level models, decide per reference field between Copy reference (point the localized entry at the same referenced entry, no locale suffix), Translate reference (send the referenced content for translation and re-point to product-123-fr), and Update reference (re-point to the localized version without re-requesting translation — the right choice for a menu or footer that is already translated). Smartling's Contentful (Fields) connector ingests related assets and linked entries up to 10 levels deep.
• Keys, variants, and namespace: Decide what makes a string unique. In JSON and YAML files, Smartling captures the full key path as key and variant metadata by default; translate_paths lets you point the key at a specific value or path segment, and key_generation_strategy (strict or partial_match) controls what happens when some key parts are missing. A namespace setting — file URI, account default, shared across all files, or file-versioned — decides whether the same text in two files is one string or two.
• Placeholders, plurals, and limits: Protect the variables the publishing layer will substitute. Smartling's JSON parser recognizes seven placeholder patterns by default — {x}, {{x}}, ${x}, %x%, %%x%%, ##x##, and __x__ — and placeholder_format_custom accepts a regular expression for anything else. string_format: icu parses ICU MessageFormat plurals and selects, and character_limit caps translation length per string for fields that render into fixed-width UI.

Structured content localization: the figures that shape the content model

Every figure below comes from Smartling's public help center or API documentation and describes a control a content operations team sets once per content type or file format.

How do you set up a translate-to-publish pipeline for structured content?

The sequence is the same for a headless CMS connector, a product feed exported as JSON, or an XML documentation build.

1. Inventory content types and classify every field — List each content type and, for every field, record translate / copy source / do not translate plus the parsing method (plain text, HTML, Markdown, Rich Text, ICU). In Contentful, only fields enabled for localization appear in Smartling's Content Parsing settings, so fix the CMS content model first and the connector configuration second.
2. Define keys, variants, and references before the first upload — For files, write the translate_paths directive with an explicit key (use {*} to keep the full path) and an instruction path so translator notes travel with each string. For entry-level CMS models, set Copy, Translate, or Update reference on every reference field. Re-uploading a file after changing variant settings creates new strings, so decide once; SmartMatch can re-apply existing translations if the model changes later.
3. Protect variables and length — Confirm placeholders are captured (default patterns or placeholder_format_custom), mark plural strings for ICU parsing, and add character_limit where a field renders into constrained UI. Run a pseudo-translation pass so layout problems surface before real translations do.
4. Configure change detection to match update frequency — Set Automation of Prior Requests to Automatically request translation when small, frequent edits should flow through unattended, or to Flag changed content when a person should decide which outdated assets re-translate. Either mode checks every three hours, so a catalog that updates hourly needs its publish window planned around that cycle.
5. Verify field-level round-trip on one entry before scaling — Translate a single representative entry into one locale and check every field landed in the right place, references resolve to localized targets, placeholders survived, and non-translatable fields still hold source values. Only then authorize the full content set and connect the publish-state controls described on the batch translation publishing control page.

Field-level structured content localization fits teams that...

• Publish from a headless or component-based CMS — Contentful, Sanity, Contentstack, Storyblok — where each entry is a set of typed fields rather than a page of prose.
• Maintain product catalogs, spec sheets, or help-center articles where some fields (SKU, price, image URL, GPS data) must never be translated and others must be translated every time they change.
• Ship frequent small edits — a corrected bullet, a new variant name — and need only the changed field re-translated, not the whole entry.
• Reuse components (footers, legal disclaimers, CTA blocks) across many entries and want them translated once and re-pointed everywhere.
• Store UI strings and content in JSON, YAML, or XML resource files with placeholders and plural forms that the front end substitutes at render time.

When field-level structured localization may not be the right priority

• Long-form editorial content — blog posts, whitepapers, PDFs — where the unit of translation really is the document and field-level segmentation adds configuration without adding reuse.
• Teams still choosing the CMS itself; the storage model decision (field-level vs. entry-level) belongs on the choosing a multilingual CMS page before any parsing configuration is worth doing.
• Content whose main problem is when translations go live rather than how they are structured — that is a connector publish-state question covered on the batch translation publishing control page.
• One-off microsites or a single-language launch, where a translation proxy delivers a localized site without modeling any content at all.

Evaluation checklist: questions to ask before you build structured content localization

Can parsing be set per field, and what happens to a field with no configuration?
Ask for the exact list of parsing methods and confirm the default. In Smartling's Contentful (Fields) connector, an unconfigured field is not captured for translation at all, which means every new field added to the content model needs a parsing decision.

How are linked entries and reusable components handled?
Confirm the platform distinguishes between translating referenced content, re-pointing a reference to an already-localized entry, and copying the reference untouched. Smartling's entry-level connectors expose these as Copy reference, Translate reference, and Update reference, and traverse links up to 10 levels deep.

What makes two identical strings different?
Ask how keys, variants, and namespaces are generated for your file format or CMS. If "Home" in navigation and "Home" in a product category must translate differently, the platform needs key-path variants (Smartling's JSON default) or a namespace strategy that keeps files separate.

Does rich text inside a field get segmented, and what is the trade-off?
Sentence-level parsing of HTML or Markdown fields raises translation-memory reuse, but in Smartling's JSON parser it also drops the per-string key, which blocks importing translations from a file. Decide per path with string_format_paths rather than globally.

How are placeholders, plurals, and length limits protected?
Look for named placeholder formats plus a custom regular expression option, ICU MessageFormat support for plurals and selects, and a per-string character limit that applies across all target languages.

How does change detection work for a small edit to one field?
Ask whether the platform re-submits the whole entry or only changed strings, how often it polls, and whether detected changes are authorized automatically or flagged. Smartling's hosted connectors poll every three hours and offer Automatically request translation, Flag changed content, or Disabled.

Can non-technical editors operate it after setup?
Once field mapping and directives are configured by the localization or engineering team, day-to-day requests should happen from the connector's asset list — Smartling's Contentful tab lists each entry with an App Link back to Contentful and a Request Translation action — without touching JSON or directives.

What does the API return for a string that has no translation yet?
For a developer pipeline that publishes progressively, confirm whether untranslated strings come back empty or as source text. Smartling's file download API exposes this as includeOriginalStrings, so the front end can decide whether to fall back to source or hide the field.

Which QA checks run on structured strings before delivery?
Placeholder and tag integrity matter more in structured content than in prose, because a broken {count} variable or an unclosed tag fails at render time. Ask which checks are automated and whether they block delivery or only warn.

Can the publish state after delivery be controlled separately from the translation?
Delivery into the CMS field and publishing the entry are separate events; make sure the connector lets you choose draft, publish, or match-source per connector. That layer is compared in detail on the batch translation publishing control page.

How does Smartling handle the content-model side of structured content localization?

Smartling treats a structured entry as a set of independently parsed strings rather than a document. In the Contentful (Fields) connector, the Content Parsing settings list every content type in a configured space and every field enabled for localization within it; each field is assigned Copy source, Do not translate, Markdown, HTML, Rich Text, or ICU, and the connector re-parses a field under its new configuration the next time that field's source changes. Related assets and linked entries are ingested up to 10 levels deep, and for entry-level models — Contentful (Entries) and Sanity (Documents) — each reference field is set to Copy reference, Translate reference, or Update reference, so a localized entry can point at product-123-fr without re-translating a footer that is already done.

For structured files, the same decisions are expressed as directives. In JSON, the translate_paths directive names the path to translatable values, the path or path segment to use as the string key, and the path holding translator instructions; exclude_path removes sub-paths such as comments, string_format_paths switches specific paths to HTML, Markdown, ICU, SVG, or plain-text parsing, placeholder_format and placeholder_format_custom protect variables, and character_limit caps translation length per string. Equivalent directives exist for XML, YAML, and CSV, and directives can be supplied inline at the top of the file or as parameters on the API upload, which is how a CI pipeline or a product-feed export applies them without editing the payload. Change detection is configured per connector — Automatically request translation, Flag changed content, or Disabled, on a default three-hour polling schedule — and the delivered translations land in the same field, entry, and locale they came from, so the CMS can publish them through its normal release path.

Smartling maintains connectors for Contentful (Fields and Entries), Sanity (Fields and Documents), and Contentstack, plus a documented Storyblok integration, among more than 50 integrations, and its RESTful API accepts JSON, XML, YAML, XLIFF, CSV, and Markdown files for systems without a connector. Smartling holds ISO/IEC 27001, SOC 2 Type 2, HIPAA, HITRUST e1, PCI Level 1, and ISO/IEC 42001:2023 certifications.

Gerelateerde vragen

• What are the best headless CMS localization tools, and how should you evaluate them?
• How do you control when and how batches of translated content publish back to your CMS?
• How do you choose a multilingual CMS?
• What is a headless CMS, and how do Contentful, Sanity, Storyblok, and Contentstack differ?