The Storyblok (TMS) plugin seamlessly connects the Storyblok content management system with the Phrase Translation Management System.
This plugin enables:
-
Sending content from Storyblok stories for translation in Phrase TMS.
-
Automatically extracting translatable content from stories.
-
Downloading and merging translated content back into Storyblok.
-
Tracking translation status and manage workflows.
Features:
-
Secure Authentication:
Encrypted credential storage with automatic token refresh and 2FA support.
-
Project Templates:
Use existing Phrase project templates to standardize translation workflows.
-
Smart Content Extraction:
Automatically identifies and extracts only translatable content, excluding technical fields.
-
Workflow Integration:
Supports Storyblok workflow stages and Phrase translation workflows.
-
Real-time Tracking:
Monitor translation job status, workflow progress, and completion metrics.
-
Automatic Merging:
Seamlessly merge translated content back into original story structure.
Content extraction
The plugin automatically identifies translatable content while filtering out technical fields and preserving story structure.
Translatable content:
Content is processed recursively through all nested structures.
-
Text and text area fields
-
Rich text content (with formatting preserved)
-
Markdown content
-
String values ≥ 2 characters
-
Nested content in arrays and objects
Automatically excluded:
The extractor intelligently identifies over 40 technical field types including Storyblok core fields, rich text structure nodes, asset metadata, linkconfigurations, and translation system fields to ensure only human-readable content is sent for translation.
-
Core fields: _uid, _editable, component
-
IDs: uuid, id, parent_id, etc.
-
Paths: slug, full_slug, path
-
URLs: filename, url, cached_url, src, href
-
Timestamps: created_at, published_at
-
Booleans: published, is_startpage
-
Rich text structure: type, marks, attrs
-
Asset fields: fieldtype, focus, content_type
-
Link fields: linktype, target, anchor, email
-
Translation system: lang, alternates, translated_slugs
To use the plugin, a Phrase TMS account with appropriate permissions and an API token are required. The API token is encrypted using AES-256 encryption and stored securely. JWT tokens obtained from the API are automatically refreshed every 24 hours to maintain secure access and auto-refresh with a five minute buffer.
The Phrase account must have either an Administrator or Project Manager role.
In the case of authentication errors, ensure that the token is correct and has not been revoked, the correct data center is being accessed, the token has the correct permissions and that the account has the correct role.
If the token has expired, it may require re-authentication by clicking Disconnect Phrase and reconnecting.
-
Authenticate with Phrase TMS: Enter an API token and select a data center (EU or US) to connect to Phrase TMS.
-
Select Stories to Translate: Browse a Storyblok space and select stories for translation.
-
Create Translation Project: Define source language, target languages, due dates, and optionally use a project template. Multiple stories can be selected.
If unable to create a translation project, ensure permissions are correct, at least one story is selected, source and target languages are valid and that template access is in place.
-
Content Auto-Extraction: Plugin automatically extracts translatable content (text, rich text, markdown) while preserving structure.
-
Upload to Phrase: Content is uploaded to Phrase TMS as translation jobs, one per story-language combination.
-
Translation in Phrase: Linguists work on content in Phrase, progressing through workflow stages.
-
Merge and Publish: Translations are merged back into Storyblok stories, ready to publish.