Content Blocks

Content blocks are structured pieces of content that contain multiple phrases within a single unit. They are perfect for managing complex, multi-phrase content like email templates, HTML sections, or structured documents.

What are Content Blocks?

Content blocks allow you to group related phrases together while maintaining their structure and context. Unlike individual phrases, content blocks preserve the HTML structure and relationships between different text elements.

Key Features

• Structured content — maintains HTML structure and formatting
• Multiple phrases — can contain many individual phrases
• Context preservation — phrases maintain their relationship to each other
• Bulk translation — translate all phrases in a content block together

Content Block Structure

Content blocks use a special syntax to mark phrases within HTML content. The syntax allows you to specify which parts of the content should be translated while preserving the overall structure.

Phrase Marking Syntax

Use the {[category]} syntax to mark phrases within your HTML content:

<div class="email-template">
    <h1>{[UI]} Welcome to our service</h1>
    <p>{[Content]} Thank you for signing up. We're excited to have you on board.</p>
    <ul>
        <li>{[UI]} Dashboard</li>
        <li>{[UI]} Settings</li>
        <li>{[UI]} Profile</li>
    </ul>
    <p>{[Content]} If you have any questions, please don't hesitate to contact us.</p>
</div>

Syntax Components

• {[ — marks the start of a translatable phrase
• Category — the category of the phrase (e.g., “UI”, “Content”, “Error”)
• ]} — marks the end of a translatable phrase
• Text content — the actual text that will be translated

Creating Content Blocks

API Request Format

Create content blocks using the POST /translatable-items endpoint with type: "content_block":

{
    "project_id": "your-project-id",
    "type": "content_block",
    "custom_id": "welcome-email-template",
    "content": "<h1>{[UI]} Welcome!</h1><p>{[Content]} Thank you for joining us.</p>",
    "category": "Email",
    "label": "Welcome Email Template",
    "phrases": [
        { "phrase": "Welcome!", "category": "UI", "translatable": true },
        { "phrase": "Thank you for joining us.", "category": "Content", "translatable": true }
    ]
}

Required Fields

• project_id — the ID of your project
• type — must be "content_block"
• custom_id — your unique identifier for the content block
• content — the HTML content with marked phrases
• category — the category of the content block
• phrases — array of phrases contained in the content block

Optional Fields

• label — human-readable identifier (auto-generated if not provided)

Content Block Examples

Email Template

<!DOCTYPE html>
<html>
<head>
    <title>{[UI]} Welcome Email</title>
</head>
<body>
    <h1>{[UI]} Welcome to {[Brand]} Langsys</h1>
    <p>{[Content]} Thank you for signing up for our translation service.</p>
    <p>{[Content]} You can now start managing your translations with ease.</p>
    <a href="/dashboard">{[UI]} Go to Dashboard</a>
</body>
</html>

Navigation Menu

<nav class="main-navigation">
    <ul>
        <li><a href="/">{[UI]} Home</a></li>
        <li><a href="/about">{[UI]} About</a></li>
        <li><a href="/services">{[UI]} Services</a></li>
        <li><a href="/contact">{[UI]} Contact</a></li>
    </ul>
</nav>

Error Page

<div class="error-page">
    <h1>{[Error]} Page Not Found</h1>
    <p>{[Error]} The page you are looking for could not be found.</p>
    <p>{[Content]} Please check the URL or return to the homepage.</p>
    <a href="/">{[UI]} Return Home</a>
</div>

Working with Content Blocks

Retrieving Translations

Content blocks are retrieved as part of the standard translation endpoint. The system returns the translated content with all phrases properly localized:

GET /translations?locale=es&project_id=your-project-id

Response Format

The response includes the content block with all phrases translated:

{
    "data": {
        "welcome-email-template": {
            "content": "<h1>¡Bienvenido!</h1><p>Gracias por unirte a nosotros.</p>",
            "phrases": [
                { "phrase": "Welcome!", "translation": "¡Bienvenido!", "category": "UI" },
                { "phrase": "Thank you for joining us.", "translation": "Gracias por unirte a nosotros.", "category": "Content" }
            ]
        }
    }
}

Best Practices

Content Organization

• Use meaningful custom IDs — choose IDs that clearly identify the content block
• Group related content — keep related phrases together in the same content block
• Use consistent categories — apply the same categorization system across your content
• Keep structure simple — avoid overly complex HTML structures

Phrase Marking

• Mark all translatable text — don’t forget to mark phrases that should be translated
• Use appropriate categories — choose categories that reflect the content type
• Avoid marking HTML tags — only mark the text content, not the HTML structure
• Be consistent — use the same category for similar types of content

Performance Considerations

• Limit content block size — very large content blocks can impact performance
• Use appropriate granularity — don’t create content blocks for single phrases
• Consider caching — cache translated content blocks when possible

Content Block vs. Phrases

Feature	Content Blocks	Phrases
Use case	Structured content, templates, complex UI	Simple text, labels, messages
Structure	Maintains HTML structure	Plain text only
Multiple phrases	Yes, can contain many phrases	No, single phrase only
Context	Preserves relationships between phrases	Independent phrases
Translation	Bulk translation of all phrases	Individual phrase translation

Next Steps

• Translation Algorithm — learn how translations are selected
• API Reference — complete API documentation