Context-Aware Translation

The BabelizeTag component and babelize.tag() function let you translate full sentences containing React elements. The entire template is sent to the translator as one unit, so word order and grammar remain correct even when segments are reordered by the target language.

The Problem

When you split a sentence across multiple DOM nodes, each fragment is translated independently. The translator doesn't know they form one sentence:

// English: "Welcome to Babelize, a platform for localization"

// ✗ Each fragment translated separately — wrong word order in Japanese
<h1>
  {babelize("Welcome to")}           // → "へようこそ" (belongs at end)
  <strong>{babelize("Babelize")}</strong>  // → "バビリゾーン"
  {babelize(", a platform")}          // → "、プラットフォーム"
  <em>{babelize("for localization")}</em> // → "ローカリゼーションのため"
</h1>

// Correct Japanese: "ローカリゼーションのためのプラットフォーム、バビリゾーンへようこそ"

The Solution

Use <BabelizeTag> to translate the full sentence as one unit:

import { BabelizeTag } from "@babelize/sdk-react";

<h1>
  <BabelizeTag
    template="Welcome to {Babelize}, a platform {for localization}"
    segments={{
      Babelize: <strong>Babelize</strong>,
      "for localization": <em>for localization</em>,
    }}
  />
</h1>

The full template is sent to the translator. Segment markers {Babelize} and {for localization} are protected from translation but provide context. The translated output preserves the markers at their correct positions for the target language:

English input:  "Welcome to {Babelize}, a platform {for localization}"

Japanese output (correct):
"ローカリゼーションのための{for localization}プラットフォーム、{Babelize}へようこそ"
                              │                                   │
                   <em>for localization</em>           <strong>Babelize</strong>

The component replaces each marker with its corresponding React element, preserving the natural word order of the target language.

babelize.tag()

For non-React usage, use babelize.tag() directly:

const result = babelize.tag("Welcome to {Babelize}, a platform {for localization}");

Returns a TagResult with a parts array:

{
  parts: [
    { type: "text", value: "ローカリゼーションのための" },
    { type: "segment", value: "for localization" },
    { type: "text", value: "プラットフォーム、" },
    { type: "segment", value: "Babelize" },
    { type: "text", value: "へようこそ" },
  ],
}

Map segments to your own elements:

const segments = {
  Babelize: <strong>Babelize</strong>,
  "for localization": <em>for localization</em>,
};

const rendered = result.parts.map((part) =>
  part.type === "segment"
    ? segments[part.value] ?? part.value
    : part.value,
);

Lockfile Integration

The build plugin discovers <BabelizeTag template="..." /> calls and extracts the template string as a single translation unit. The full template appears in the lockfile alongside regular strings:

{
  "strings": {
    "Welcome to {Babelize}, a platform {for localization}": {
      "ja": "{Babelize}へようこそ",
      "fr": "Bienvenue dans {Babelize}, une plateforme {pour la localisation}"
    }
  }
}

This ensures segment translations are pre-built and served instantly in production.

Context-Aware Translation

The Problem

The Solution

babelize.tag()

Lockfile Integration

On this page