KirbyTags

Kirby Content Translator supports translation of KirbyTags while preserving their structure and functionality. You can configure which types of KirbyTags and which specific attributes within those tags should be translated, giving you fine-grained control over the translation process.

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

The plugin protects KirbyTags structurally: tags are extracted from the surrounding content before translation and reassembled from the original parse afterwards, preserving syntax and attribute names exactly. Both the Panel and the PHP API use the same <cN/> placeholder approach – the strategy never sees the original tag text, so URLs, UUIDs, and untranslatable attributes are guaranteed to survive.

Basic Configuration

Add the kirbyTags option to your plugin configuration to enable selective translation. You can specify which KirbyTag types to translate and which attributes within those tags should be processed. Here's an example configuration:

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

When using the Content Translator view button or section, you can also configure KirbyTags directly in your blueprint. This allows you to define which tags and attributes should be translated per section:

type: content-translator
kirbyTags:
  # Translate link text and title in `(link: ...)` KirbyTags
  link:
    - text
    - title
  # Translate image alt text and title in `(image: ...)` KirbyTags
  image:
    - alt
    - title
    - caption
  # Translate file text and title in `(file: ...)` KirbyTags
  file:
    - text
    - title
  # Translate email text and title in `(email: ...)` KirbyTags
  email:
    - text
    - title
  # Translate video caption in `(video: ...)` KirbyTags
  video:
    - caption

Translation Example

For example, this configuration 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)

Common Translatable Attributes

The configuration is an associative array where:

• Keys are KirbyTag types (e.g., link, image, file)
• Values are arrays of attribute names that should be translated

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
        ]
    ]
];

Error Handling

KirbyTags are protected structurally on both the Panel and the PHP API. The pipeline runs KirbyText::split() over textarea and markdown fields:

• Tags are extracted from the prose and replaced with opaque <c0/>, <c1/>, … placeholders.
• The strategy receives the placeholder-decorated prose plus any translatable tag attributes as separate units – never the raw tag.
• After translation, placeholders are rewritten back to fully-formed KirbyTags using the original parse data. URLs, filenames, UUIDs, and untranslatable attributes pass through verbatim.

The CopilotAIStrategy additionally counts placeholders in the source vs. the translation – any unit where the AI lost or invented a <cN/> token is dropped to source text and the content-translator.translate:warning hook fires.