From 57986aac21c62da8febe111eef3fbe0928be4037 Mon Sep 17 00:00:00 2001
From: "Anderson J. Eccel" <116097999+andersonjeccel@users.noreply.github.com>
Date: Wed, 18 Jun 2025 16:54:42 -0300
Subject: [PATCH 1/2] Adding docs for flash messages

---
 docs/design/flash_messages.rst | 52 ++++++++++++++++++++++++++++++++++
 docs/index.rst                 |  1 +
 2 files changed, 53 insertions(+)
 create mode 100644 docs/design/flash_messages.rst

diff --git a/docs/design/flash_messages.rst b/docs/design/flash_messages.rst
new file mode 100644
index 00000000..f0a8400a
--- /dev/null
+++ b/docs/design/flash_messages.rst
@@ -0,0 +1,52 @@
+Implementing flash messages
+###########################
+
+Flash messages are temporary notifications that appear at the top of the page to inform users about the result of an action.
+
+Backend (PHP) implementation
+****************************
+
+**In controllers:**
+
+.. code-block:: php
+
+   // Success message
+   $this->addFlashMessage('mautic.core.notice.created', [
+       '%name%' => $entity->getName()
+   ]);
+
+   // Error message
+   $this->addFlashMessage('mautic.core.error.generic', [], 'error');
+
+The first parameter is the translation key, the second is an array of parameters for the translation, and the third is the message type (default is ``notice``).
+
+Frontend (JavaScript) implementation
+************************************
+
+1. **Add translation strings**
+
+Add your translation strings to ``{bundle}/Translations/en_US/messages.ini`` (or the relevant locale/domain):
+
+.. code-block:: ini
+
+   mautic.core.notice.my_success_message="Success message here!"
+   mautic.core.error.my_error_message="Error message here!"
+
+2. **Create and display translated flash messages**
+
+Create the flash message using one of these helper functions:
+- Mautic.addFlashMessage(message) - Generic flash message
+- Mautic.addInfoFlashMessage(message) - Info/success flash message
+- Mautic.addErrorFlashMessage(message) - Error flash message
+
+Pass the result to Mautic.setFlashes() to display it.
+
+.. code-block:: javascript
+
+   var message = Mautic.translate('mautic.core.notice.my_success_message');
+   var flashMessage = Mautic.addInfoFlashMessage(message);
+   Mautic.setFlashes(flashMessage);
+
+   var message = Mautic.translate('mautic.core.error.my_error_message');
+   var flashMessage = Mautic.addErrorFlashMessage(message);
+   Mautic.setFlashes(flashMessage);
diff --git a/docs/index.rst b/docs/index.rst
index df41b368..088b45c8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -62,6 +62,7 @@ There are several ways to support Mautic other than contributing with code.
    design/feedback
    design/labelling
    design/notifications
+   design/flash_messages
    design/protip
    design/quick_filters
    design/retrieving_system_information

From 297d9fca6d5c27b1cd4477f176e450d07c2bd87b Mon Sep 17 00:00:00 2001
From: "Anderson J. Eccel" <116097999+andersonjeccel@users.noreply.github.com>
Date: Wed, 18 Jun 2025 16:57:16 -0300
Subject: [PATCH 2/2] Fixing wrong path

---
 docs/design/flash_messages.rst | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/docs/design/flash_messages.rst b/docs/design/flash_messages.rst
index f0a8400a..01c731f2 100644
--- a/docs/design/flash_messages.rst
+++ b/docs/design/flash_messages.rst
@@ -6,6 +6,8 @@ Flash messages are temporary notifications that appear at the top of the page to
 Backend (PHP) implementation
 ****************************
 
+Add your translation strings to ``{bundle}/Translations/en_US/flashes.ini``:
+
 **In controllers:**
 
 .. code-block:: php
@@ -23,17 +25,13 @@ The first parameter is the translation key, the second is an array of parameters
 Frontend (JavaScript) implementation
 ************************************
 
-1. **Add translation strings**
-
-Add your translation strings to ``{bundle}/Translations/en_US/messages.ini`` (or the relevant locale/domain):
+Add your translation strings to ``{bundle}/Translations/en_US/javascript.ini``:
 
 .. code-block:: ini
 
    mautic.core.notice.my_success_message="Success message here!"
    mautic.core.error.my_error_message="Error message here!"
 
-2. **Create and display translated flash messages**
-
 Create the flash message using one of these helper functions:
 - Mautic.addFlashMessage(message) - Generic flash message
 - Mautic.addInfoFlashMessage(message) - Info/success flash message