Content Translation Guide

Learn how to use BlokMCP to translate content across multiple languages efficiently with AI assistance.

Overview

BlokMCP makes it easy to manage multilingual content by allowing you to:

Copy stories to create translation versions
Use AI to translate content fields
Maintain consistent structure across languages
Update translations in bulk

What you'll learn:

Creating language-specific story versions
AI-assisted content translation
Managing translation workflows
Best practices for multilingual sites

Prerequisites

BlokMCP connected to your MCP client
Management token with story creation permissions
Multilingual space setup in Storyblok
Claude or another AI assistant

Basic Translation Workflow

Scenario 1: Translate Single Story

Goal: Create a Spanish version of an English blog post.

I have a blog post "Getting Started with Storyblok" (ID: 123456).
Create a Spanish version by:
1. Get the original story content
2. Duplicate it with slug "comenzando-con-storyblok"
3. Translate the title to "Comenzando con Storyblok"
4. Keep it as a draft for review

Claude will:

Fetch the original story
Duplicate it with the new slug
Update the title field
Leave other fields for manual or AI-assisted translation

Scenario 2: AI-Assisted Field Translation

Goal: Translate specific content fields using AI.

For story 123456, translate these fields to Spanish:
- headline
- intro_text
- body_content

Keep the same structure and formatting.

Claude will:

Read the original content
Translate each field using its AI capabilities
Update the Spanish version story
Preserve markdown, links, and formatting

Scenario 3: Bulk Translation Setup

Goal: Create language versions for all blog posts.

For all stories in the "blog/en" folder:
1. Create corresponding stories in "blog/es" folder
2. Copy the structure but leave content for translation
3. Tag them with "needs-translation"

Process:

Lists all English blog posts
Creates Spanish skeleton stories
Tags for translation workflow
Reports which stories were created

Advanced Translation Workflows

Multi-Language Content Sync

Scenario: Keep structure synchronized across language versions.

I updated the component structure for blog posts.
For each blog post in English:
1. Find its Spanish equivalent (by matching slugs)
2. Update the Spanish version to use the same component structure
3. Preserve existing Spanish translations
4. Report any stories without Spanish versions

Translation Status Tracking

Scenario: Track which content needs translation.

For all stories tagged "needs-translation":
1. Show me the story title and last modified date
2. Count how many are in each language folder
3. Identify stories older than 30 days

This helps prioritize translation work.

Partial Translation Updates

Scenario: Update only changed fields.

The English version of "Product Guide" was updated.
For the Spanish version:
1. Compare the last_modified dates
2. If English is newer, tag Spanish version "needs-update"
3. List which fields changed in English

Translation Best Practices

1. Folder Structure

Organize by language:

/content/en/
  /blog/
  /products/
/content/es/
  /blog/
  /products/

Or use Storyblok's internationalization:

/blog/
  story-slug (default language)
  story-slug?lang=es

2. Slug Naming Conventions

Option A: Translated slugs

English: getting-started
Spanish: comenzando

Option B: Language prefix

English: en-getting-started
Spanish: es-getting-started

Option C: Same slug, different folders

English: /en/getting-started
Spanish: /es/getting-started

3. Tagging Strategy

Use tags to track translation status:

needs-translation - New content not yet translated
translation-in-progress - Being translated
translation-complete - Fully translated
needs-update - Source changed, translation outdated

4. Field-Level Translation

Always translate:

Headlines and titles
Body content
Meta descriptions
Alt text for images

Usually keep original:

URLs and links (unless localized)
Technical identifiers
Component structure
Asset references

Consider locale-specific:

Date formats
Currency symbols
Phone numbers
Address formats

AI Translation Tips

1. Context Preservation

Translate this blog post to Spanish.
Context: This is for a technical audience.
Maintain formal tone and technical terminology.

2. Batch Field Translation

For this story, translate these fields to French:
- title: "..."
- intro: "..."
- body: "..."

Preserve all markdown formatting and links.

3. Brand Consistency

When translating, keep these terms in English:
- "Storyblok"
- "Headless CMS"

Use these Spanish equivalents:
- "content management" → "gestión de contenido"

Common Workflows

Workflow 1: New Content Translation

Author creates English content
Publish English version
BlokMCP duplicates to Spanish folder
AI translates text fields
Human reviews and refines
Publish Spanish version

New blog post "AI in 2024" was just published in English.
1. Duplicate it to the Spanish blog folder
2. Translate title, intro, and body to Spanish
3. Tag it "needs-review"
4. Leave as draft

Workflow 2: Update Existing Translations

English content updated
System detects change
Tags translations as outdated
Translator reviews changes
Updates translation
Republish

English version of "Product Guide" was updated 2 days ago.
Spanish version is 30 days old.
1. Tag Spanish version "needs-update"
2. Show me what changed in English
3. Update those specific fields in Spanish

Workflow 3: Bulk Translation Push

Quarterly translation sprint
Identify all untranslated content
Batch create translation skeletons
AI pre-translates
Human review and publish

Find all stories in /en/blog/ from last quarter.
For each one:
1. Check if Spanish version exists in /es/blog/
2. If not, create skeleton story
3. Pre-translate with AI
4. Tag "translation-review"

Handling Different Content Types

Blog Posts

Translate blog post 123456 to Spanish:
- Full translation of all text
- Keep same category tags
- Update publish date to today
- Link to English version in metadata

Product Pages

Translate product page to German:
- Translate description and features
- Keep SKU and technical specs in English
- Convert prices to EUR with current rates
- Update availability status for EU market

Marketing Pages

Translate landing page to French:
- Adapt copy for French market
- Keep brand voice and messaging
- Localize CTAs ("Learn More" → "En savoir plus")
- Update images if culturally specific

Quality Assurance

Translation Checklist

For Spanish translation of "Getting Started":
1. ✓ Title translated correctly
2. ✓ Body content fully translated
3. ✓ Links work and point to Spanish versions
4. ✓ Images have Spanish alt text
5. ✓ Meta description translated
6. ✓ No broken formatting
7. ✓ Same component structure as English
8. ✓ Slug is SEO-friendly in Spanish

Automated Checks

For all stories tagged "translation-complete":
1. Verify all text fields have content
2. Check no fields still contain English text
3. Ensure dates are in correct format
4. Confirm required fields are filled

Troubleshooting

Missing Translations

Problem: Spanish version doesn't exist for new English content.

Solution:

Find all English blog posts from last month.
List which ones don't have Spanish equivalents.
Create draft Spanish versions for review.

Outdated Translations

Problem: Translation is older than source content.

Solution:

Compare modification dates between English and Spanish versions.
Tag Spanish stories where English was updated more recently.

Inconsistent Structure

Problem: Language versions use different components.

Solution:

For blog post 123, compare component structure
between English and Spanish versions.
Update Spanish to match English structure.

Quick Reference

Common Translation Commands

# Duplicate for translation
"Duplicate story 123 to /es/ folder as draft"

# AI translate
"Translate this story's text fields to Spanish"

# Find missing translations
"Which English blogs don't have Spanish versions?"

# Update outdated
"Update Spanish version to match English changes"

# Bulk create
"Create Spanish skeletons for all /en/blog/ posts"

# Track status
"Show translation status for all product pages"

Need help with translations? Ask Claude to guide you through the translation workflow or check out our conversation starters!