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 uses Kirby's built-in KirbyTag parser to safely decode, translate, and reconstruct tags without breaking their syntax.

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

Common translatable attributes:

• text – Link text, button text, display text
• title – Tooltips, titles, hover text
• alt – Image alternative text
• caption – Image or video captions
• value – The main value of a KirbyTag (use with caution)

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

The plugin includes error handling for KirbyTags to ensure that translation does not break content:

1. Parse Errors: If a KirbyTag cannot be parsed, it's wrapped in <span translate="no"> to prevent breaking.
2. Reconstruction Errors: If a translated tag cannot be properly reconstructed, the original tag is preserved.
3. Debug Mode: When Kirby's debug mode is enabled, parse errors are thrown for easier debugging.

Performance Considerations

• Only include KirbyTag types that actually contain translatable content to ensure good performance and avoid unnecessary translations.
• Test thoroughly to ensure the translation process doesn't break any existing content or functionality.