Extended the examples to showcase translations for custom page blocks… (#2933)

mnocon · adriendupuis · mnocon · commit 9cc4ec8cf561 · 2025-10-16T00:04:49.000+02:00
* Extended the examples to showcase translations for custom page blocks and form fields

* Update docs/content_management/pages/create_custom_page_block.md

Co-authored-by: Adrien Dupuis &lt;61695653+adriendupuis@users.noreply.github.com&gt;

---------

Co-authored-by: Adrien Dupuis &lt;61695653+adriendupuis@users.noreply.github.com&gt;
diff --git a/code_samples/forms/custom_form_field/config/packages/form_builder.yaml b/code_samples/forms/custom_form_field/config/packages/form_builder.yaml
@@ -1,18 +1,18 @@
 ibexa_form_builder:
     fields:
         country:
-            name: Country
-            category: Custom form fields
+            name: country_field.name
+            category: custom_category.name
             thumbnail: '/bundles/ibexaadminuiassets/vendors/ids-assets/dist/img/all-icons.svg#pins-locations'
             attributes:
                 label:
-                    name: Display label
+                    name: country_field.label.name
                     type: string
                     validators:
                         not_blank:
                             message: You must provide a label for the field
                 help:
-                    name: Help text
+                    name: country_field.help.name
                     type: string
             validators:
                 required: ~
diff --git a/code_samples/page/custom_page_block/config/packages/page_blocks.yaml b/code_samples/page/custom_page_block/config/packages/page_blocks.yaml
@@ -1,29 +1,29 @@
 ibexa_fieldtype_page:
     blocks:
         event:
-            name: Event Block
-            category: Custom
+            name: event_block.name
+            category: custom_category.name
             thumbnail: /bundles/ibexaadminuiassets/vendors/ids-assets/dist/img/all-icons.svg#calendar
             configuration_template: '@ibexadesign/blocks/event/config.html.twig'
             views:
                 default:
                     template: '@ibexadesign/blocks/event/template.html.twig'
-                    name: Default view
+                    name: event_block.view.default
                     priority: -255
                 featured:
                     template: '@ibexadesign/blocks/event/featured_template.html.twig'
-                    name: Featured view
+                    name: event_block.view.featured
                     priority: 50
             attributes:
                 name:
                     type: text
-                    name: Event name
+                    name: event_block.name.name
                     validators:
                         not_blank:
-                            message: Please provide a name
+                            message: validators.message.event_block.name.validator.not_blank
                 category:
                     type: select
-                    name: Select a category
+                    name: event_block.category.name
                     value: visual
                     options:
                         multiple: true
@@ -33,18 +33,18 @@ ibexa_fieldtype_page:
                             'Sports': sports
                 event:
                     type: embed
-                    name: Event
+                    name: event_block.event.name
                     options:
                         udw_config_name: block_event_embed
                     validators:
                         not_blank:
-                            message: Please select an event
+                            message: validators.message.event_block.embed.validator.not_blank
                         content_type:
-                            message: Please select an event
+                            message: validators.message.event_block.embed.validator.content_type
                             options:
                                 types: ['event']
                         regexp:
-                            message: Choose a content item
+                            message: validators.message.event_block.embed.validator.content_item
                             options:
                                 pattern: '/[0-9]+/'
 
diff --git a/docs/content_management/forms/create_custom_form_field.md b/docs/content_management/forms/create_custom_form_field.md
@@ -16,6 +16,16 @@ For example, to create a Country Form field in the "Custom form fields" category
 [[= include_file('code_samples/forms/custom_form_field/config/packages/form_builder.yaml') =]]
 ```
 
+and provide the translations for the labels in `translations/ibexa_form_builder.en.yaml`:
+
+``` yaml
+country_field.name: Country
+custom_category.name: Custom form fields
+
+country_field.label.name: Display label
+country_field.help.name: Help text
+```
+
 Available attribute types are:
 
 |Type|Description|
diff --git a/docs/content_management/pages/create_custom_page_block.md b/docs/content_management/pages/create_custom_page_block.md
@@ -21,9 +21,38 @@ First, add the following [YAML configuration](configuration.md#configuration-fil
 [[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 0, 6) =]][[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 16, 49) =]]
 ```
 
+And provide the translations for the labels:
+
+- in `translations/ibexa_page_builder_block_config.en.yaml`:
+
+``` yaml
+event_block.view.default: Default
+event_block.view.featured: Featured
+
+event_block.name.name: Name
+event_block.category.name: Category
+event_block.event.name: Event
+```
+
+- in `translations/ibexa_page_fieldtype.en.yaml`:
+
+``` yaml
+custom_category.name: Custom category
+event_block.name: Event
+```
+
+- in `translations/validators.en.yaml`:
+
+``` yaml
+validators.message.event_block.name.validator.not_blank: Event name should not be blank.
+validators.message.event_block.embed.validator.not_blank: Event content should not be blank.
+validators.message.event_block.embed.validator.content_type: Event content should be of type "event".
+validators.message.event_block.embed.validator.content_item: Event content should have a numerical ID.
+```
+
 `event` is the internal name for the block, and `name` indicates the name under which the block is available in the interface.
 You also set up the category in the **Page blocks** toolbox that the block appears in.
-In this case, it doesn't show up with the rest of the built-in blocks, but in a separate "Custom" category.
+In this case, it doesn't show up with the rest of the built-in blocks, but in a separate "Custom category" category.
 The thumbnail for the block can be one of the pre-existing icons, like in the example above, or you can use a custom SVG file.
 
 A block can have multiple attributes that you edit when adding it to a page.
diff --git a/docs/content_management/pages/page_block_attributes.md b/docs/content_management/pages/page_block_attributes.md
@@ -14,7 +14,7 @@ Each block can have the following properties:
 | Attribute    | Description                                                                                                  |
 |--------------|--------------------------------------------------------------------------------------------------------------|
 | `type`       | Attribute type.                                                                                              |
-| `name`       | (Optional) The displayed name for the attribute. You can omit it, block identifier is then used as the name. |
+| `name`       | (Optional) The displayed name for the attribute. You can omit it, block identifier is then used as the name. Translatable using the `ibexa_page_builder_block_config` translation domain. |
 | `value`      | (Optional) The default value for the attribute.                                                              |
 | `category`   | (Optional) The tab where the attribute is displayed in the block edit modal.                                 |
 | `validators` | (Optional) [Validators](page_block_validators.md) checking the attribute value.                              |
diff --git a/docs/content_management/pages/page_blocks.md b/docs/content_management/pages/page_blocks.md
@@ -20,8 +20,8 @@ Each configured block has an identifier and the following settings:
 
 | Setting                  | Description                                                                                                                                                   |
 |--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `name`                   | Name of the block used in the Page Builder interface.                                                                                                         |
-| `category`               | Category in the Page Builder **Page blocks** toolbox that the block is shown in.                                                                                        |
+| `name`                   | Name of the block used in the Page Builder interface. Translatable using the `ibexa_page_fieldtype` translation domain.                                                                                                         |
+| `category`               | Category in the Page Builder **Page blocks** toolbox that the block is shown in. Translatable using the `ibexa_page_fieldtype` translation domain.                                                                                        |
 | `thumbnail`              | Thumbnail used in the Page Builder **Page blocks** toolbox.                                                                                                             |
 | `views`                  | Available [templates for the block](#block-templates).                                                                                                        |
 | `visible`                | (Optional) Toggles the block's visibility in the Page Builder **Page blocks** toolbox. Remove the block from the layout before you publish another version of the page. |
@@ -51,6 +51,7 @@ You can overwrite the following properties in the existing blocks:
 
 Page blocks can have multiple templates.
 This allows you to create different styles for each block and let the editor choose them when adding the block from the UI.
+They names are translatable using the `ibexa_page_builder_block_config` translation domain.
 
 ``` yaml
 [[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 0, 3) =]][[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 7, 16) =]]
diff --git a/docs/tutorials/page_and_form_tutorial/4_create_a_custom_block.md b/docs/tutorials/page_and_form_tutorial/4_create_a_custom_block.md
@@ -67,3 +67,5 @@ The Tip of the Day block displays a random Tip from the "Tips" folder.
 Refresh the page a few more times and you can see the tip change randomly.
 
 ![Random Block with a Tip](enterprise_tut_random_block.png "Random Block with a Tip")
+
+To learn more about custom Page Builder blocks, see [Create custom page block](create_custom_page_block.md).
