Drupal 8+: create custom block plugin configs translatable

Profile picture for user a.berramou
Azz-eddine BERRAMOU 24 September, 2023

Sometimes, you might need a custom block plugin with extra settings. 

If your website is multilingual, it's important to make sure these settings can be translated. 

In this post, we'll focus on how to do that.

  1. Create a block plugin 

For creating a block plugin we need to create CustomBlockExampleBlock.php file at [MY_MODULE]/src/Plugin/Block

<?php declare(strict_types = 1);
namespace Drupal\drupal_api_messages\Plugin\Block;
use Drupal\Core\Access\AccessResult;
use Drupal\Core\Block\BlockBase;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Session\AccountInterface;
 * Provides a custom block translated block.
 * @Block(
 *   id = "custom_block_example",
 *   admin_label = @Translation("Custom block translated"),
 *   category = @Translation("Custom"),
 * )
final class CustomBlockExampleBlock extends BlockBase {
   * {@inheritdoc}
  public function defaultConfiguration(): array {
    return [
      'message' => $this->t('Hello world!'),
   * {@inheritdoc}
  public function blockForm($form, FormStateInterface $form_state): array {
    $form['message'] = [
      '#type' => 'textarea',
      '#title' => $this->t('Example'),
      '#default_value' => $this->configuration['message'],
    return $form;
   * {@inheritdoc}
  public function blockSubmit($form, FormStateInterface $form_state): void {
    $this->configuration['message'] = $form_state->getValue('message');
   * {@inheritdoc}
  public function build(): array {
    $build['content'] = [
      '#markup' => $this->configuration['message'],
    return $build;
  1. Add your block to a region  
    You are now able to place your block to a specific region.

    adding block 
    3. Translate the configuration of your block

    You can now attempt to translate the block; however, you will notice that only the title is accessible for translation, and the message config that we added in the blockForm it's not available for translation.  
    Translate block 
    4. Make block plugin configs translatable.

    To do so we need two things 

    1. Declare a schema [MY_MODULE].schema.yml in our module at at [MY_MODULE]/config/schema  

        type: block_settings
        label: 'Custom block translated block'
            type: label # Declare type as label not string.
            label: Example
    2.  Change the type of the config should be label not string otherwise it will not be accessible for translate.

       The data type 'label' is an extension of 'string' and allows the multilingual system to translate our property.

If we return to block translation, we now have the message configuration available for translation:

translatable block

And like this we make our custom block plugin configurations translatable.
For additional details on how configuration translation works, please refer to these two articles.