View Button & Section Configuration

Kirby Content Translator can be added to Panel views via a view button (recommended) or a section. Both approaches support the same configuration properties and can be used together.

View Button Configuration

The Content Translator view button can be added to any Panel view (site, page, file) alongside the default buttons like the languages dropdown. It provides a dropdown menu with translation actions.

Basic Setup

To add the content-translator button to a Panel view, set the buttons option in the corresponding blueprint:

buttons:
  - open
  - preview
  - content-translator
  - languages

buttons:
  - open
  - preview
  - settings
  - content-translator
  - languages
  - status

buttons:
  - open
  - settings
  - content-translator
  - languages

Advanced Configuration

Configure the button behavior with props in your blueprints:

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

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

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

Section Configuration

As an alternative to the view button, you can add a Content Translator section to your blueprint. The section displays translation controls directly within the page content area.

Basic Setup

Add the Content Translator section to any blueprint:

sections:
  contentTranslator:
    type: content-translator

The section provides the same functionality as the view button but is placed within the blueprint layout.

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

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

Advanced Configuration

Configure the section behavior with props:

sections:
  contentTranslator:
    type: content-translator

sections:
  contentTranslator:
    type: content-translator
    title: true
    slug: true
    kirbyTags:
      link:
        - text
        - title
      image:
        - alt
        - caption

Available Properties

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

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:

importFrom: all

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

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:

import: false

batch Boolean

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

This property is only available for the default language:

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:

batch: false

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.

title: true

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.

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:

confirm: false

fieldTypes Array

This is one of the most important properties. 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:

• blocks
• layout
• list
• object
• structure
• tags
• text
• textarea
• writer
• markdown (from the markdown field plugin)
• table (from the table field plugin)

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

fieldTypes:
  - text
  - textarea

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.

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

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:

excludeFields:
  - description
  - summary

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.

kirbyTags:
  link: [text, title]
  image: [alt, title, caption]
  file: [text, title]
  email: [text, title]
  video: [caption]

For the full per-tag attribute reference and translation behavior, see the KirbyTags Configuration guide.

systemPrompt String v3.10.0+

Override the AI translation system prompt for this specific section or view button. Takes precedence over the global ai.systemPrompt config option.

systemPrompt: >
  You are a medical translator.
  Preserve clinical terminology
  and abbreviations.

Configuration Precedence

Properties are applied in the following order (later values 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' => true
    ]
];

sections:
  contentTranslator:
    type: content-translator
    fieldTypes: # Overrides global config
      - blocks
      - text
      - textarea
    # confirm: true inherited from global config

buttons:
  content-translator:
    confirm: false # Overrides global config

Localization

Override the plugin's default Panel labels by adding translations to your Kirby installation's languages directory. Useful when "Synchronize" reads better than "Import" for your editors, or when your project uses a language the plugin doesn't ship translations for.

return [
    'code' => 'en',
    'name' => 'English',
    // ... Other language configuration
    'translations' => [
        'johannschopplich.content-translator.import' => 'Synchronize'
    ]
];