Kirby Tools
v3.8.1Hub

View Button & Section Configuration

Configure Content Translator view buttons and sections in your blueprints as needed.

Kirby Content Translator supports configuration through view buttons and sections, providing fine-grained control over translation behavior. Both approaches support the same configuration options and can be used together.

View Button Configuration

View buttons are available in Kirby 5+. For Kirby 4, the view button is shown by default and can be controlled via the viewButton global option.

In Kirby 5, you can add the Content Translator view button to any blueprint and configure its behavior with props:

buttons:
  preview: true
  content-translator:
    title: true
    slug: true
    excludeFields:
      - description
  languages: true

Section Configuration

Add the Content Translator section to any blueprint and configure its behavior with props:

sections:
  contentTranslator:
    type: content-translator

This is how the basic section will look in the default language:

Content Translator section in default language

When switching to secondary languages, the section buttons will change to Import and Translate:

Content Translator section in secondary language

Available Options

When configured globally, these options will apply to both view buttons and sections. Local configurations can override them.

label String

Custom label for the Content Translator view button or section. The default depends on the Panel language (e.g., "Content Translator" for English).

To change the label to "Translate":

buttons:
  content-translator:
    label: Translate

importFrom String

Controls import direction. Set to all to allow importing from any language to any language, including overwriting the default language with content from secondary languages:

buttons:
  content-translator:
    importFrom: all

The button text will indicate that importing from secondary languages is allowed:

Content Translator section with import all option
By default, Kirby Content Translator only allows importing from the default language to secondary languages to prevent accidental overwrites of the default language content. It renders the → All Languages button for batch translations in the default language:

Content Translator section in default language
By default, only importing from the default language to secondary languages is allowed to prevent accidental overwrites. Use importFrom: all with caution.

import Boolean

Enable or disable content importing functionality entirely.

To hide the import actions in the view button or section, set the import key to false:

buttons:
  content-translator:
    import: false

batch Boolean

Enable or disable batch translation (translating to multiple languages at once).

This option is only available for the default language:

Content Translator section in default language
Unlike per-language translation, this translation process is not reversible in the Panel and is handled server-side. Use it with caution, as it may take a while to translate all content.

When the button is clicked, a dialog with checkboxes for each secondary language is displayed. You can select the languages to translate the content into. Click the Translate button to start the batch mode translation process.

Content Translator batch translation dialog

For security reasons, the confirmation modal cannot be disabled with the confirm property.

If you want to disable batch translations for multiple languages at once, you can set the batch property to false. This will hide the batch mode translation button in the view button or section:

buttons:
  content-translator:
    batch: false
This option was called bulk in previous versions. The bulk option is still supported for backwards compatibility.

title Boolean

Include the model title in import and translation operations. This is particularly useful for pages, where the title is often a key piece of content.

buttons:
  content-translator:
    title: true
Title changes cannot be reverted in the content history, unlike field changes. Use with caution.

slug Boolean

Similar to the title property, the model slug can be included in import and translation operations. This is particularly useful for pages, where the slug is derived from the title. The slug will be generated from the translated title.

buttons:
  content-translator:
    slug: true

confirm Boolean

Show confirmation dialogs before import or translation operations. This is enabled by default to prevent accidental overwrites of content.

If you want to skip this dialog, you can set the confirm key to false:

buttons:
  content-translator:
    confirm: false

fieldTypes Array

This is one of the most important options. Specify which field types to include in import and translation operations. By default, the plugin imports or translates all text-like fields: list, tags, text, textarea, writer, and markdown. These fields can be nested within blocks, layout, object, and structure fields.

Default field types:

For example, to include only text and textarea fields in the translation:

buttons:
  content-translator:
    fieldTypes:
      - text
      - textarea
To translate text fields within blocks, you must include both blocks and text in the fieldTypes array.
When translate: false is set on a field, it will be ignored by the translation process, regardless of the fieldTypes configuration.

includeFields Array

Specify specific fields to include in import and translation operations (field names are case-insensitive). This is useful if you want to translate only specific fields, either nested or not. The fieldTypes property is still respected.

When using the includeFields property, all fields are filtered by their key. The key is case-insensitive, meaning that text and Text are treated as the same field.

For example, to include only company and author fields in the translation:

buttons:
  content-translator:
    includeFields:
      - company
      - author

excludeFields Array

Specify fields to exclude from the import and translation process (field names are case-insensitive). This is useful if you want to exclude specific fields while still including all fields of certain types via fieldTypes.

For example, to exclude description and summary fields from translation:

buttons:
  content-translator:
    excludeFields:
      - description
      - summary
Fields with translate: false in their blueprint definition are automatically excluded.

kirbyTags Object

Configure selective translation of KirbyTag types and its attributes (e.g., link text, image alt text). By default, all KirbyTags are excluded to preserve URLs, filenames, and technical attributes.

buttons:
  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

For detailed KirbyTags configuration, see the KirbyTags Configuration guide.

Configuration Precedence

Configuration options are applied in the following order (later options override earlier ones):

  1. Default values (built into the plugin)
  2. Global configuration (in config.php)
  3. View button & section props (in blueprints)
return [
    'johannschopplich.content-translator' => [
        'fieldTypes' => ['text', 'textarea'], // Applied globally
        'confirm' => false,
    ]
];

Global Configuration

Configure translation providers, API keys, and global defaults.

Custom Translator Functions

Use custom translation services or define your own translation logic.