---
title: Migration von Chamaileon
description: Chamaileon-E-Mail-Templates mit @templatical/import-chamaileon in das Templatical-Format konvertieren.
---

# Migration von Chamaileon

Diese Anleitung richtet sich an Teams, die E-Mail-Templates in [Chamaileon](https://chamaileon.io) erstellt haben — im gehosteten Editor oder über ein Produkt, das das SDK einbettet — und auf Templaticals visuellen Editor wechseln möchten. **`@templatical/import-chamaileon`** konvertiert ein Chamaileon-Persist-Dokument in Templaticals `TemplateContent`-Format. Installieren Sie es, führen Sie es aus, und nutzen Sie die folgenden Abschnitte, um alles nachzuarbeiten, was es nicht automatisch abbilden kann.

Die Eingabe ist `editorInstance.methods.getDocument()`, nicht `getEmailHtml()` / der HTML-Generator.

## Installation

::: code-group

```bash [npm]
npm install @templatical/import-chamaileon
```

```bash [pnpm]
pnpm add @templatical/import-chamaileon
```

```bash [yarn]
yarn add @templatical/import-chamaileon
```

```bash [bun]
bun add @templatical/import-chamaileon
```

:::

### Ohne Build-Schritt (CDN)

Sie können es auch von einem CDN laden:

```html
<script type="module">
  import { convertChamaileonTemplate } from 'https://cdn.jsdelivr.net/npm/@templatical/import-chamaileon/+esm';
  // ...dann konvertieren wie im Abschnitt „Verwendung“ unten
</script>
```

## Verwendung {#usage}

```ts
import { convertChamaileonTemplate } from '@templatical/import-chamaileon';

const document = await editorInstance.methods.getDocument();

const { content, report } = convertChamaileonTemplate(document);

const editor = await init({
  container: '#editor',
  content,
});

console.log(report);
```

[Im Playground öffnen](https://play.templatical.com/scenes/import-chamaileon)

`convertChamaileonTemplate` arbeitet synchron und gibt ein `ImportResult` zurück mit:

- `content` — das konvertierte `TemplateContent`, bereit für den Editor
- `report` — ein Konvertierungsbericht mit dem Status jedes erzeugten Blocks (`converted`, `approximated`, `html-fallback` oder `skipped`)

Es akzeptiert das Dokument auch als serialisierten JSON-String, für Aufrufer, die es auf diese Weise speichern oder übertragen.

::: tip
Übergeben Sie das Persist-Dokument aus `getDocument()`. Dieses Objekt ist `{ body, variables?, components?, title?, previewText?, subjectLine?, fontFiles? }` mit `body.type === "body"`. Der HTML-Generator (`getEmailHtml()`) ist eine andere Oberfläche — kompiliertes Tabellen-Markup, das zu [`@templatical/import-html`](/de/guide/migration-from-html) gehört, nicht zu diesem Paket. Ein Rateversuch zwischen den beiden würde Markup durch den falschen Konverter schicken.

E-Mail-JSON 2.0 bis 4.1 wird nach einem Schlüssel-Normalisierer akzeptiert. Kebab-Case-Styles (`background-color`) und CamelCase (`backgroundColor`) sind dieselbe Eigenschaft, zwei Versionen. Inline-Farbobjekte `{ reference, default }` werden auf `default` aufgelöst, oder auf den passenden Eintrag in `variables[]`, wenn `default` fehlt. Der `reference`-Name ist ein Design-Token, kein Empfängerfeld, und wird daher nicht als Merge-Tag gespeichert.
:::

## Optionen {#options}

`convertChamaileonTemplate` akzeptiert als zweites Argument `ConvertChamaileonOptions`. `defaultLocale?: string` setzt `settings.locale`, wenn die Quelle keine Standardsprache angibt; andernfalls gilt `"en"`. Eine deklarierte Standardsprache hat Vorrang. Sprachcodes werden von `_` nach `-` normalisiert. Eine deklarierte Standardsprache oder ein `defaultLocale`, das danach kein Sprach-Tag ist, etwa ein Platzhalter <code v-pre>{{lang}}</code>, wird mit einem `report.warnings`-Eintrag ignoriert, der den Wert nennt; dann gilt der nächste gültige Wert oder `"en"`.

Dieses JSON-Format liefert dem Importer keine Standardsprache. Übergeben Sie die vom Host konfigurierte Sprache als `defaultLocale`.

```ts
export interface ConvertChamaileonOptions {
  defaultLocale?: string;
}
```

## Bericht

Jeder Eintrag in `report.entries` beschreibt einen erzeugten Block:

| Status | Bedeutung |
|---|---|
| `converted` | Auf einen Templatical-Block abgebildet, ohne Verlust. |
| `approximated` | Auf den richtigen Block abgebildet, mit einer Begrenzung oder einem Flatten — `note` nennt die Änderung. |
| `html-fallback` | Keine Block-Entsprechung vorhanden; der rohe Knoten bleibt als JSON in einem `HtmlBlock` erhalten. |
| `skipped` | Eine leere Schleife oder Bedingung — es gab keine Kinder zu konvertieren. |

```ts
console.log(report.summary);
// { total: 24, converted: 18, approximated: 5, htmlFallback: 0, skipped: 1 }

for (const entry of report.entries) {
  if (entry.status === 'approximated') {
    console.warn(`${entry.sourceTag} approximiert:`, entry.note);
  }
}
```

Eine `note` bei einem `approximated`-Eintrag nennt den ursprünglichen Wert. `report.warnings` trägt Verluste auf Dokumentebene, die an keinem einzelnen Eintrag hängen — eine nicht-leere `subjectLine` oder `fontFiles`, ein `backgroundImage` des Bodys und eine Anzahl von Farbvariablen, die auf ihre Default-Werte aufgelöst wurden.

## Dokumentform

Chamaileon speichert ein Design als Baum typisierter Knoten unter `body`:

```
document
  body (type "body")
    children: fullwidth | block-level-loop | block-level-conditional
      fullwidth.children: box | multicolumn | leaf
        box.children: box | multicolumn | leaf
        multicolumn.children: column only
          column.children: box | multicolumn | leaf
```

Blätter in der dokumentierten Elementliste: `text`, `typed-text`, `button`, `image`, `dynamic-image`, `divider`, `social`, `video`, `code`. `eid` wird verworfen — Templatical vergibt eigene IDs. `placeholder` ist Editor-Chrome und wird übersprungen. `customData` wird ignoriert.

- **Chamaileon** speichert diesen Persist-Baum, plus optionale `variables[]` (Design-Tokens) und `fontFiles`.
- **Templatical** speichert Templates als JSON-Baum mit typisierten Blöcken (`SectionBlock`, `ParagraphBlock` usw.) und rendert diesen Baum beim Export zu MJML.

`@templatical/import-chamaileon` durchläuft `body.children`, flacht `box` und verschachtelte `multicolumn` ab und baut daraus die entsprechenden Templatical-Blöcke. Die Mapping-Tabelle unten zeigt, was er dabei umsetzt.

## Visueller Neuaufbau

Bei einer Handvoll Templates ist der Neuaufbau von Hand neben einer Chamaileon-Vorschau oft schneller, als ein Paket zu installieren:

1. Öffnen Sie das Chamaileon-Design — den Editor selbst oder eine Vorschau von `getEmailHtml()` — in einem Fenster.
2. Öffnen Sie den Templatical-Editor (oder den [Playground](https://play.templatical.com)) daneben.
3. Nutzen Sie diese Vorschau als visuelles Ziel. Übergeben Sie `getEmailHtml()` nicht an diesen Konverter.
4. Ziehen Sie die entsprechenden Templatical-Blöcke hinein (siehe [Mapping-Tabelle](#chamaileon-node-mapping) unten).
5. Kopieren Sie Textinhalte direkt. Hosten Sie Bilder über Ihre Medienbibliothek neu.
6. Bilden Sie Styling über Templaticals [Design-Tokens](/de/guide/theming) ab.

Die meisten Chamaileon-Templates sind in 10–20 Minuten umgezogen, sobald Sie eines oder zwei gemacht haben. Bei größeren Mengen führen Sie zuerst `@templatical/import-chamaileon` aus und nutzen diesen Pfad nur, um nachzuarbeiten, was als `approximated`, `skipped` oder als `html-fallback`-Block gelandet ist.

## Renderer-Prüfung

Sobald ein Template in Templatical vorliegt — importiert oder von Hand nachgebaut:

```ts
import { renderToMjml } from '@templatical/renderer';

const mjml = await renderToMjml(content);
```

Ein visueller Vergleich mit Chamaileons eigener Vorschau zeigt, was der Bericht nicht zeigen kann. Mehrere der unten genannten Verluste — `hoverBackgroundColor`, seitenweise Rahmen auf Blättern — werden an der Stelle verworfen, an der sie gelesen werden, mit einer `note`, wenn der Konverter irgendwo andocken kann.

Es gibt kein Round-Trip-Orakel. Templatical rendert kein Chamaileon-JSON, und dieses Paket verarbeitet `getEmailHtml()` nicht.

## Knoten-Abbildung {#chamaileon-node-mapping}

| Chamaileon | Templatical-Block | Hinweise |
|---|---|---|
| `body` | Template-`settings` | `bodyWidth` → `settings.width`; `backgroundColor` → `settings.backgroundColor`; `previewText` → `settings.preheaderText`, wenn nicht leer; ein `backgroundImage` wird verworfen und in `report.warnings` genannt. |
| `fullwidth` | `SectionBlock` | Äußeres `backgroundColor` → `wrapper.backgroundColor` mit `wrapper.fullWidth: true`; `contentBackgroundColor` → `section.styles.backgroundColor`; `contentPadding*` → Padding. Ein Fullwidth ohne `multicolumn` ist `columns: "1"`. `contentBackgroundImage` → `backgroundImage`; `backgroundImage` und Farbe des Bands folgen [Hintergrundbilder](#hintergrundbilder). |
| `box` | In das Elternelement abgeflacht | Transparente Boxen verschwinden ohne Eintrag. Eine bemalte Box, die einziges Kind eines Fullwidth ohne Content-Fill ist, kopiert diese Farbe auf die Sektion. Eine bemalte Box unter Geschwistern wird abgeflacht, `approximated`. Das Hintergrundbild einer einzelnen Box wandert auf die Sektion, wenn das Fullwidth kein `contentBackgroundImage` hat; hat es eines, oder unter Geschwistern, wird das Box-Bild verworfen und vermerkt, `approximated`. |
| `multicolumn` + `column` | Section-`columns` / `children[i]` | Der Anteil einer Spalte ist ihre px-`style.width` geteilt durch die Summe der Breiten der Zeile; das Inhalts-Padding der Fullwidth und die Spacer der Multicolumn liegen außerhalb der Spalten und sind daher keine Anteile. Eine Spalte ohne lesbare px-Breite zählt mit Chamaileons Standardwert `300px`. Anteile innerhalb von 2 Prozentpunkten eines Layouts (`1`, `2`, `3`, `4`, `2-1`, `1-2`, `3-1`, `1-3`, `1-2-1`) behalten dieses Layout: `280px` / `280px` ist `"2"` und `150px` / `300px` / `150px` ist `"1-2-1"`. Jedes andere Verhältnis von zwei bis vier Spalten behält das gleichmäßige Layout dieser Anzahl und setzt [`columnWidths`](/de/guide/sections-and-columns#custom-column-widths) auf die auf 100 skalierten Anteile: `360px` / `240px` ist `"2"` mit `[60, 40]`. Beide bleiben `converted`. Eine Breite, die nicht über 0 liegt, behält das gleichmäßige Layout ohne `columnWidths`, `approximated`. Der Platz einer Spalte, an dem ein Bild oder Video gemessen wird, ist ihr Anteil an der inneren Box, also an `bodyWidth` abzüglich des linken und rechten Inhalts-Paddings der Fullwidth: Eine 50-%-Spalte in einem 600px-Body mit 20px Inhalts-Padding auf jeder Seite hat 280px. Eine verschachtelte `multicolumn` kann kein verschachtelter `SectionBlock` werden — innere Spalten fließen in die Elternspalte, `approximated`. |
| `text` | `TitleBlock` oder `ParagraphBlock` | Abgeleitet aus dem HTML in `attrs.text`: eine einzelne Überschrift, die den gesamten Inhalt umschließt, wird zum Title; alles andere zum Paragraph. |
| `typed-text` | `TitleBlock` oder `ParagraphBlock` | `style.subType === "title"` → Title; `"list"` → Paragraph, `approximated`; sonst Paragraph. |
| `button` | `ButtonBlock` | `href` → `url`; Beschriftung ohne Tags. `style.lineHeight` wird zu `lineHeight`, seine px geteilt durch die `fontSize` des Buttons (15px, wenn ungesetzt): Chamaileons Standard `25px` auf `18px` ergibt `1.39`. Ein Wert, der 1.2 ergibt, oder keiner bleibt ungesetzt; ein nicht lesbarer wird mit 1.2 importiert, `approximated`. Ein ungesetztes Fill ist ein Outlined-Button — Fill wird `#ffffff` (nicht das Factory-`#333333`), der Eintrag ist `approximated`. |
| `image` | `ImageBlock` | `src` aus `attrs`, dann `style`; `altText` → `alt`. Eine px-`style.width` wird `"full"`, sobald sie die Spalte abzüglich des seitlichen Paddings des Bildes erreicht. |
| `dynamic-image` | `ImageBlock` | `approximated`; die `note` nennt den Quelltyp. |
| `divider` | `DividerBlock` | 2.0 `attrs.lineStyle` und 4.1 `style.width` / `type` / `color` (Linienstärke, nicht Blockbreite). |
| `social` | `SocialIconsBlock` | `elements[]` ist die Quelle der Wahrheit. Unbekannte Plattformnamen werden zu `website`. Icon-Größe rastet auf 24 / 32 / 48 px. |
| `video` | `VideoBlock` | `link` → `url`; `src` → `thumbnailUrl`. Ein fehlendes Thumbnail bleibt der leere Factory-String. |
| `code` | `HtmlBlock` | Aus `attrs.html` / `attrs.code` / `attrs.content` (erstes gesetztes Feld). |
| `block-level-loop`, `block-level-conditional`, `branch`, `loop`, `conditional` | Kinder, oder Skip | Leer → `skipped`. Nicht leer → Kinder werden konvertiert, als wäre der Wrapper nicht da; jeder erzeugte Eintrag ist `approximated`. Der Ausdruck wird nicht auf `displayCondition` abgebildet. |
| Jeder andere `type` | `HtmlBlock` | Der rohe Knoten bleibt als JSON erhalten, markiert als `html-fallback`. |

`hideOnMobile` / `hideOnDesktop` werden auf `visibility` abgebildet. Fehlt, wenn beide Flags falsch sind.

### Hintergrundbilder

Das Bild der Sektion eines Fullwidth ist, vom nächstliegenden an:

1. `contentBackgroundImage`, die Inhaltsfläche, die die Sektion zeichnet.
2. Das `backgroundImage` einer Box, die das einzige Kind des Fullwidth ist; es wandert nach oben, solange es kein `contentBackgroundImage` gibt.
3. Das `backgroundImage` des Bands wird zu `wrapper.backgroundImage` mit `wrapper.fullWidth: true`, auch hinter einer bemalten Inhaltsfläche. Ist dieses Bild die einzige Farbe, liegt die Bandfarbe mit ihm auf dem Wrapper und der Sektionshintergrund bleibt ungesetzt.

Hat die Sektion ein eigenes Bild, wird die Farbe des Bands mit einer Notiz verworfen, statt `wrapper.backgroundColor` zu werden: Outlook für Desktop malt eine Wrapper-Farbe über das Bild der Sektion. Das Bild des Bands liegt trotzdem auf dem Wrapper.

`backgroundSize`, `backgroundPosition` und `backgroundRepeat` (sowie ihre `content…`-Formen) werden mitgenommen, wo nicht gesetzt mit den CSS-Anfangswerten. Eine Größe, die eine Seite füllt (`100%`, `100% auto` oder eine px-Breite mindestens so groß wie die E-Mail), wird `cover`, jede andere Länge oder Prozentangabe `auto`; eine Prozent-Position rastet auf das nächste von links, Mitte und rechts (oben, Mitte und unten) ein, eine Länge auf den linken bzw. oberen Rand; `repeat-x`, `repeat-y`, `round` und `space` werden zu `repeat`. Jeder solche Wert wird vermerkt.

## Verlustbehaftete Konvertierung

- **Verschachtelte `multicolumn`** — eine Zeile innerhalb einer Spalte kann kein verschachtelter `SectionBlock` werden. Die Kinder der inneren Spalten werden in Dokumentreihenfolge in die Elternspalte eingefügt, `approximated`, `note` `"nested multicolumn flattened (N columns)"`. Blätter werden konvertiert; die Geometrie ist der Verlust.
- **5+ Spalten** — Templatical unterstützt diese Spalten-Layouts (`1`, `2`, `3`, `4`, `2-1`, `1-2`, `3-1`, `1-3`, `1-2-1`). Vier gleich breite Spalten bleiben `"4"`. Eine `multicolumn` mit fünf oder mehr Spalten wird auf `"4"` gefaltet; überzählige Kinder hängen an den letzten Slot, `approximated`, und die `note` nennt die Obergrenze von vier Spalten.
- **Outlined-Buttons** — ungesetztes `background-color` plus farbiger Rahmen hat keine Templatical-Entsprechung. Nach `createButtonBlock` wird Fill als `#ffffff` geschrieben, damit das Factory-`#333333` einen Ghost-Button nicht in eine dunkle Pille verwandelt. Der Outline entfällt; der Eintrag ist `approximated`.
- **Schleifen und Bedingungen** — Chamaileons `attrs.expression` ist kein Liquid und keine MJML-Anzeigebedingungs-Syntax. Leere Knoten `skipped`. Gefüllte Knoten konvertieren ihre Kinder und verwerfen die Verzweigung; den Ausdruck in `displayCondition` zu stecken, würde über den Dialekt lügen.
- **Box-Bemalung unter Geschwistern** — eine verschachtelte Box mit echtem Fill, Padding, Radius oder Hintergrundbild, die nicht das einzige Kind eines sonst unbemalten Fullwidth ist, wird abgeflacht. Die Bemalung entfällt, `approximated`, und ein verworfenes Hintergrundbild wird vermerkt. Eine neue Top-Level-Sektion würde die Zeile teilen; eine verschachtelte Sektion ist in einer Spalte unzulässig.
- **Variablen-Referenzen** — `{ reference, default }` wird auf eine konkrete Farbe aufgelöst. Der Referenzname überlebt nicht als Merge-Tag.
- **Social-Icon-Größen und unbekannte Plattformen** — Größe rastet auf small / medium / large; ein unbekannter `type` wird zu `website`.
- **Überschriften-Ebenen** — `TitleBlock` unterstützt die Ebenen 1 bis 4. Ein einzelnes `<h5>` oder `<h6>` wird auf 4 begrenzt.
- **Block-IDs** — jeder importierte Block erhält eine neu generierte ID. Chamaileons `eid` wird verworfen.

::: tip
Verschachtelte Spalten und bemalte Boxen werden abgeflacht, weil MJML eine Sektion innerhalb einer Spalte verbietet und `addBlock` das ebenfalls tut. Ein erfundener verschachtelter `SectionBlock` würde nicht rendern; erfundene zusätzliche Top-Level-Sektionen würden eine Zeile teilen, die eine einzige Band war. Blätter werden in beiden Fällen konvertiert. Leere Schleifen werden übersprungen statt zu einem undurchsichtigen `HtmlBlock`, sodass eine gefüllte Schleife aus Produktzeilen als konvertierte Kinder erhalten bleibt.
:::

## Nicht abgebildete Felder

- **`subjectLine`** — Templatical-Templates haben kein Betreff-Feld. Ein nicht-leerer Wert wird in `report.warnings` genannt.
- **`fontFiles`** — keine Schrift-Datei-Tabelle auf Dokumentebene. Ein nicht-leeres Objekt wird in `report.warnings` genannt. Text, der davon abhing, wird in der Ersatzschriftart gerendert.
- **`title`** (der Dokumentname) — still; er ist nicht empfängerseitig.
- **`hoverBackgroundColor`** — kein Hover-Fill auf `ButtonBlock`.
- **Seitenweise Rahmen auf Blättern** — an der Stelle verworfen, an der sie gelesen werden.
- **`fullWidthOnMobile` als reines Mobil-Flag** — auf Templatical-Blöcken nicht ausgedrückt.
- **`components[]`** — 4.x-Stilvorlagen-Bibliothek. Nicht in v1; der eigene Style am Knoten gilt weiterhin.
- **`lock` / `marker`** — Editor-Chrome; ignoriert.
- **`placeholder`** — Block-Bibliotheks-Chrome auf `fullwidth`; übersprungen.

Ein frisch importiertes Template scheitert bei der Ankunft häufig an den Barrierefreiheits-Regeln von `@templatical/quality`, und der `validate`-Befehl des [Agent Skill](/de/guide/agent-skill) beendet sich dabei mit einem Exit-Code ungleich 0. Aus Chamaileon exportierte Bilder tragen typischerweise keinen `alt`-Text, und der Importer übernimmt diese Lücke originalgetreu — eine Beschreibung zu erfinden wäre selbst ein Anti-Pattern für Barrierefreiheit. Die strukturelle Validierung besteht; die Befunde betreffen den Inhalt. Fügen Sie den importierten Bildern Alt-Text hinzu, und die Befunde verschwinden.

## Weitere Fälle

[Eröffnen Sie eine Diskussion](https://github.com/templatical/sdk/discussions) mit einem geschwärzten Ausschnitt Ihres Chamaileon-`getDocument()`-JSON und dem, was Sie erreichen wollen. Wir nutzen diese Rückmeldungen, um die Abdeckung von `@templatical/import-chamaileon` zu verbessern.
