From 171f7585c2b0f25373e1c8929e5352f359f05866 Mon Sep 17 00:00:00 2001
From: Julie Lenaerts <julielenaerts@gmail.com>
Date: Wed, 26 Mar 2025 11:10:02 +0100
Subject: [PATCH] WIP translation conventions

---
 docs/source/development/translations.rst | 107 +++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 docs/source/development/translations.rst

diff --git a/docs/source/development/translations.rst b/docs/source/development/translations.rst
new file mode 100644
index 000000000..77cde49a7
--- /dev/null
+++ b/docs/source/development/translations.rst
@@ -0,0 +1,107 @@
+Translations
+************
+
+One source of truth
+===================
+
+As of January 2025 we have opted to use one source of truth for translations in our backend as well as our frontend.
+You will find translations still being present in i18ns files for our vue components, but these will slowly be replaced.
+The goal is to only use the messages.{locale}.yaml files to create our translations and keys.
+
+Each time we do `symfony console cache:clear` a javascript and typescript file are generated containing all the keys and the corresponding translations.
+These can then be imported into our vue components together with the `trans` method, for use in the vue templates.
+
+Vue import example
+^^^^^^^^^^^^^^^^^^
+
+. code-block:: js
+    import {
+        ACTIVITY_BLOC_PERSONS,
+        ACTIVITY_BLOC_PERSONS_ASSOCIATED,
+        ACTIVITY_BLOC_THIRDPARTY,
+        ACTIVITY_BLOC_USERS,
+        ACTIVITY_ADD_PERSONS,
+        trans,
+    } from "translator";
+
+Setup
+=====
+
+For development purposes we generally make use of the chill-bundles standalone project. Here the new translation setup will work out of the box.
+
+However when working on a customer chill instance (with a root project and a chill-bundles implementation) it is required to execute the chill translations recipe
+using the command
+
+Translation key conventions
+===========================
+
+When adding new translation keys we have chosen to adhere to the following conventions as of April 2025.
+Older translation keys will gradually be adapted to respect these conventions.
+
+Conventions
+^^^^^^^^^^^
+
+Entity related messages
+-----------------------
+
+Translation keys will be structured as followed as follows:
+
+`[bundle].[entity].[page or component].[action / message]`
+
+. code-block:: yaml
+    person:
+        household:
+            index:
+                edit_comment: "Mettre à jour le commentaire"
+
+
+
+So the key to be used will be `person.household.index.edit_comment` when used in a twig template
+or
+`PERSON_HOUSEHOLD_INDEX_EDIT_COMMENT` when used in a vue component.
+
+
+Export related messages
+-----------------------
+
+Translation keys will be structured as followed as follows:
+
+[bundle]
+    |
+    |__ export
+        |
+        |__ ['count | list' | 'filter' | 'aggregator']
+            |
+            |__ [export | filter | aggregator - name] OR [ properties (end of hierarchy) ]
+                |
+                |__ [action / message]
+
+ex. Filter
+
+. code-block:: yaml
+    activity:
+        export:
+            filter:
+                by_users_job:
+                    title: Filtrer les échanges par type
+                    'Filtered activity by users job: only %jobs%': 'Filtré par métier d''au moins un utilisateur participant: seulement %jobs%'
+
+ex. Export type
+
+. code-block:: yaml
+    activity:
+        export:
+            count:
+                count_persons_on_activity:
+                    title: Nombre d'usagers concernés par les échanges
+            list:
+                activities_by_parcours:
+                    title: Liste des échanges liés à un parcours
+
+ex. Export properties shared by a certain export type
+
+. code-block:: yaml
+    activity:
+        export:
+            list:
+                users ids: Identifiant des utilisateurs