KirbyTags

Kirby Content Translator translates the KirbyTag attributes you choose and preserves the rest of each tag.

Usage

When the plugin encounters KirbyTags in textarea or markdown fields, it can either:

1. Exclude all KirbyTags from translation (default behavior)
2. Selectively translate specific attributes of configured KirbyTag types while preserving URLs, filenames, and other technical attributes

Protection is structural, not prompt-based: tags are removed before translation and restored afterwards. The Panel and the PHP API produce the same result.

Basic Configuration

Add the kirbyTags option to your plugin configuration to enable selective translation:

return [
    'johannschopplich.content-translator' => [
        'kirbyTags' => [
            'link' => ['text', 'title'],            // Translate link text and title
            'image' => ['alt', 'title', 'caption'], // Translate image descriptions
            'file' => ['text', 'title'],            // Translate download link text
            'email' => ['text', 'title'],           // Translate email link text
            'video' => ['caption'],                 // Translate video captions
            // Add more tag types as needed
        ]
    ]
];

Blueprint Configuration

A view button or section can set its own map per blueprint through its kirbyTags property.

Translation Example

For example, the configuration above translates the text and title attributes of link tags. Other attributes, such as the URL, will remain unchanged to ensure that links continue to function correctly after translation.

The content might look like this before and after translation (from English to German):

-(link: https://example.com text: Visit our website title: To homepage)
+(link: https://example.com text: Besuchen Sie unsere Website title: Zur Startseite)

Keys are KirbyTag types, values are the attribute names to translate. Any attribute of any tag type works, including tags from your own plugins – text, title, alt, and caption are simply the ones that usually hold prose.

Translating the Field Value

In advanced scenarios, you may want to translate the entire value of a KirbyTag, such as a quote with both the quote text and author. To include the main value of a KirbyTag in the translation, add value to the attributes array:

return [
    'johannschopplich.content-translator' => [
        'kirbyTags' => [
            'quote' => ['value', 'author'] // Translate both the main quote and author
        ]
    ]
];

When a Model Breaks a Placeholder

A translation that damages a tag is discarded, the field keeps its source text, and the content-translator.translate:warning hook fires with the reason placeholder mismatch. Untranslated prose is the failure mode – never a mangled tag. This holds for DeepL, AI, and any custom Strategy.

The protection covers textarea and markdown fields. A KirbyTag in a text, writer, list, or tags field reaches the provider as ordinary prose and is not checked. Keep KirbyTags in textarea or markdown fields, or exclude the fields that hold them.