View Button & Section Configuration
Kirby Content Translator supports configuration through view buttons and sections, giving you fine-grained control over translation behavior. Both approaches support the same configuration options and can be used together.
View Button Configuration
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
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
Add the Content Translator section to any blueprint and configure its behavior with props:
sections:
contentTranslator:
type: content-translator
sections:
contentTranslator:
type: content-translator
title: true
slug: true
kirbyTags:
link:
- text
- title
image:
- alt
- caption
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:

Available Options
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).
For example, to change the label to "Translate":
buttons:
content-translator:
label: Translate
sections:
contentTranslator:
type: 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
sections:
contentTranslator:
type: content-translator
importFrom: all
The button text will indicate that importing from secondary languages is allowed:


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
sections:
contentTranslator:
type: 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:

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.

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
sections:
contentTranslator:
type: content-translator
batch: false
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
sections:
contentTranslator:
type: content-translator
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.
buttons:
content-translator:
slug: true
sections:
contentTranslator:
type: 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
sections:
contentTranslator:
type: 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:
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:
buttons:
content-translator:
fieldTypes:
- text
- textarea
sections:
contentTranslator:
type: content-translator
fieldTypes:
- text
- textarea
blocks
, you must include both blocks
and text
in the fieldTypes
array.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.
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
sections:
contentTranslator:
type: 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
sections:
contentTranslator:
type: content-translator
excludeFields:
- description
- summary
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
sections:
contentTranslator:
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
For detailed KirbyTags configuration, see the KirbyTags Configuration guide.
Configuration Precedence
Configuration options are applied in the following order (later options override earlier ones):
- Default values (built into the plugin)
- Global configuration (in
config.php
) - View button & section props (in blueprints)
return [
'johannschopplich.content-translator' => [
'fieldTypes' => ['text', 'textarea'], // Applied globally
'confirm' => false,
]
];
sections:
contentTranslator:
type: content-translator
fieldTypes: # Overrides global config
- blocks
- text
- textarea
# confirm: false inherited from global config
buttons:
content-translator:
confirm: true # Overrides global config