Translatable Items

Translatable items are the core building blocks of content in Langsys. They represent pieces of text that need to be translated from your base locale to your target locales. Langsys supports two types of translatable items: phrases and content blocks.

What are Translatable Items?

Translatable items are the fundamental units of content that your application needs to translate. They can be:

• Individual phrases — short pieces of text like button labels, error messages, or navigation items
• Content blocks — larger pieces of structured content like HTML sections, paragraphs, or complex UI components

Key Characteristics

• Shared across organizations — if the same text exists in multiple projects, it shares the same ID and translations
• Locale-specific — each translatable item can have translations for multiple target locales
• Context-aware — content blocks maintain the relationship between their constituent phrases
• Version controlled — all changes are tracked and can be reverted

Phrases

Phrases are individual pieces of text that need translation. They are the most common type of translatable item and are perfect for:

• Button labels (“Save”, “Cancel”, “Submit”)
• Error messages (“Invalid email address”)
• Navigation items (“Home”, “About”, “Contact”)
• Form labels (“First Name”, “Email Address”)
• Status messages (“Loading…”, “Success!”)

Phrase Properties

• Text content — the actual text that needs translation
• Category — optional categorization (e.g., “UI”, “Error”, “Navigation”)
• Translatable flag — whether the phrase should be translated or kept in the original language
• Word count — automatically calculated for billing purposes

Content Blocks

Content blocks are structured pieces of content that contain multiple phrases. They are ideal for:

• HTML sections with multiple text elements
• Email templates with headers, body, and footers
• Complex UI components with multiple text elements
• Document sections with titles, paragraphs, and lists

Content Block Properties

• Custom ID — a unique identifier you provide to reference the content block
• HTML Content — the structured content with embedded phrases
• Category — optional categorization for organization
• Label — a human-readable identifier (auto-generated if not provided)
• Phrases — the individual phrases contained within the content block

Content Block Structure

Content blocks use a special syntax to mark phrases within HTML content:

<ul>
    <li>{[UI]} Home</li>
    <li>{[UI]} About</li>
    <li>{[UI]} Contact</li>
</ul>

The {[UI]} syntax marks phrases that should be translated, where:

• {[ — marks the start of a phrase
• UI — the category of the phrase
• ]} — marks the end of a phrase

Working with Translatable Items

Creating Translatable Items

You can create translatable items using the POST /api/translatable-items endpoint. The request accepts a project_id and a translatable_items array containing phrases and/or content blocks:

{
    "project_id": "your-project-id",
    "translatable_items": [
        { "phrase": "Welcome to our app", "category": "UI", "translatable": true },
        { "phrase": "Save", "category": "UI", "translatable": true }
    ]
}

To include content blocks in the same request, add objects with the content block fields (custom_id, content, label) alongside the phrase objects.

Retrieving Translations

Use the GET /translations endpoint to retrieve the best available translations for your translatable items:

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

Best Practices

• Use phrases for simple text — individual words, labels, and short messages
• Use content blocks for complex content — HTML sections, email templates, and structured content
• Choose meaningful categories — this helps organize and filter your content
• Mark non-translatable content — set translatable: false for proper nouns, brand names, and technical terms
• Use consistent naming — this makes it easier to manage your content over time

Integration Examples

Frontend Integration

// Fetch translations for Spanish (using API key authentication)
const translations = await fetch('/api/translations?locale=es', {
    headers: { 'X-Authorization': 'YOUR_API_KEY' }
});

// Use in your components
<button>{translations['welcome-message']}</button>

Backend Integration

// Create new phrases (using API key authentication)
const response = await fetch('/api/translatable-items', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-Authorization': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
        project_id: 'your-project-id',
        translatable_items: [{
            phrase: 'New feature available',
            category: 'UI',
            translatable: true
        }]
    })
});

Next Steps

• Content Blocks — learn more about structured content
• Translation Algorithm — understand how translations are selected
• API Reference — complete API documentation