Kirby Content Translator can be added to Panel views via a view button (recommended) or a section. Both approaches share their 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. Listing buttons replaces Kirby's defaults, so name the ones you want to keep – the default set differs per model, and content-translator goes wherever it suits the view:

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

buttons:
  - open
  - preview
  - "-" # Kirby's default divider
  - settings
  - content-translator
  - languages
  - status

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

Add the Button to Every View

To add the button to every site, page, or file view without editing each blueprint, set Kirby's panel.viewButtons option. It replaces the defaults the same way a blueprint list does, and a blueprint that sets buttons wins over it:

return [
    'panel' => [
        'viewButtons' => [
            'site' => ['open', 'preview', 'content-translator', 'languages'],
            'page' => ['open', 'preview', '-', 'settings', 'content-translator', 'languages', 'status'],
            'file' => ['open', 'settings', 'content-translator', 'languages']
        ]
    ]
];

The option takes the same list or map form as a blueprint, so the properties below can be set here too. Only cascade has to stay in the blueprint.

Advanced Configuration

Switch the list to a map when you need to pass props. A map replaces the defaults the same way a list does, so keep naming every button you want – true renders one with its own defaults:

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

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

buttons:
  open: 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 runs the same translation as the view button but is placed within the blueprint layout. It also accepts one property the view button does not: systemPrompt.

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
    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 – in English, "Translator" for the view button and "Content Translator" for the section.

To change the label to "Translate":

label: Translate

This property is per-blueprint only. To rename the button or section project-wide, override the johannschopplich.content-translator.viewButton.label and johannschopplich.content-translator.label keys under Localization.

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

To hide the import actions, set import to false:

import: false

batch Boolean

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

This property only applies in the default language, where the batch action appears.

A batch run reads the saved content of the default language, so save your changes there before starting one. A language with unsaved changes is not translated, so save or discard them first. Translation Results lists what a run reports per language.

To hide the batch action, set batch to false:

batch: false

title Boolean

Include the model title in import and translation operations. Without it, the title stays as it is, which on a page without its own translation is the default language's title.

Default: false

title: true

slug Boolean

Similar to the title property, the model slug can be included in import and translation operations. Kirby builds the slug from the translated title with the target language's slug rules, so slug: true also translates the title. The default language's slug never changes, since that would rename the page folder.

Default: false

slug: true

confirm Boolean

Show a confirmation dialog before an import overwrites the current language. Disabled by default – import runs on the first click.

confirm: true

fieldTypes Array

Specify which field types take part in import and translation. A container type in the list opens its contents but does not translate them, so a text field inside a blocks field needs both blocks and text listed.

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 the fields to include in import and translation operations. Names are matched case-insensitively. The list narrows the blueprint's top-level fields; everything nested inside a block, structure, layout, or object is reached through its top-level parent rather than by its own name. The fieldTypes property is still respected.

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

includeFields:
  - company
  - author

excludeFields Array

Specify the top-level fields to exclude from the import and translation process. Useful to drop 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.

cascade String | Array

Also translate the pages and files a Kirby query names, such as the host's own files or the module pages of a page builder. The value is one Kirby query or a list of them. The models they find are always saved directly.

cascade: page.files

This property is per-blueprint only; there is no global counterpart. See Translate Related Pages and Files for the queries, the rules for titles and unsaved changes, and a Kirby Modules example.

systemPrompt String

Override the AI translation system prompt for this specific section, taking precedence over the global ai.systemPrompt config option. Sections only – the view button does not declare this property and silently ignores it, so a per-view override has to go through the global option.

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

theme String

Controls the visual appearance and color theme of the button. View button only – the section does not declare this property and silently ignores it.

Default: notice-icon
Options: passive, white, info, positive, warning, notice, negative, love, aqua, purple, dark, *-icon variants (e.g., positive-icon, negative-icon)

theme: positive-icon

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