---
title: "Migration"
description: "Upgrade notes for breaking and notable changes – strategy interface, view-button defaults, HTML tag handling."
canonical_url: "https://kirby.tools/docs/content-translator/getting-started/migration"
---

# Migration

> Upgrade notes for breaking and notable changes – strategy interface, view-button defaults, HTML tag handling.

## Migrating to v3.14 (Drop Reasons)

The reasons the [`translate:warning`](/docs/content-translator/advanced/hooks#drop-reasons) hook reports were renamed. A handler matching the old strings stops matching.

<table>
<thead>
  <tr>
    <th>
      Before
    </th>
    
    <th>
      After
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        placeholder count mismatch
      </code>
    </td>
    
    <td>
      <code>
        placeholder mismatch
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        empty or non-string translation
      </code>
    </td>
    
    <td>
      <code>
        empty translation
      </code>
      
      , <code>
        non-string translation
      </code>
    </td>
  </tr>
</tbody>
</table>

`missing translation` is new. A strategy returning fewer entries than it was given units used to be dropped silently.

For custom strategies, an empty string is now a failed unit rather than a translation, so the field keeps its source text instead of being blanked.

## Migrating to v3.11 (Strategy Refactor)

v3.11 introduces a typed `Strategy` interface and a unified `strategy` config option. **No breaking changes** – existing code keeps working unchanged. Two deprecations to watch for v4:

<warning>

- `johannschopplich.content-translator.translateFn` – migrate to `'strategy' => $closure`. Signature is identical.
- `JohannSchopplich\ContentTranslator\KirbyText::translateText()` – migrate to `Translator::translateText()`. Same routing, same result.

</warning>

### `translateFn` → `strategy`

```diff [config.php]
return [
     'johannschopplich.content-translator' => [
-        'translateFn' => function (string $text, string $target, ?string $source) { /* … */ },
+        'strategy' => function (string $text, string $target, ?string $source) { /* … */ },
     ],
 ];
```

When both keys are set, `strategy` wins.

### `KirbyText::translateText()` → `Translator::translateText()`

```diff
-use JohannSchopplich\ContentTranslator\KirbyText;
-$translated = KirbyText::translateText($text, 'de', 'en', $kirbyTags);
+use JohannSchopplich\ContentTranslator\Translator;
+$translated = Translator::translateText($text, 'de', 'en');
```

The new pipeline routes through the configured strategy and handles KirbyTags structurally without per-call configuration.

<callout color="info" icon="i-ri-arrow-right-line" to="/docs/content-translator/php-classes/strategies">

For the new architecture, see **PHP Classes → Strategies**.

</callout>

---

Every page of this site as Markdown: <https://kirby.tools/sitemap.md>