docs(uib): localize your app (#2821)

Covers [PROD-336](https://bonitasoft.atlassian.net/browse/PROD-336)

[PROD-336]:
https://bonitasoft.atlassian.net/browse/PROD-336?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

modules/applications/applications-nav.adoc

@@ -22,6 +22,7 @@
    **** xref:ui-builder/how-to-upload-multiple-documents.adoc[Upload multiple documents simultaneously]
    **** xref:ui-builder/bonita-ui-builder-best-practices.adoc[Best practices]
     ***** xref:ui-builder/how-to-avoid-unnecessary-information-messages.adoc[Avoid unnecessary information messages]
+    ***** xref:ui-builder/how-to-localize-your-application.adoc[Localize your application for various languages]
     ***** xref:ui-builder/how-to-use-mutable-js-variable.adoc[Use mutable JS variable]
     ***** xref:ui-builder/how-to-retrieve-user-avatar.adoc[Retrieve user avatar image]
   *** xref:ui-builder/resources.adoc[Resources]

modules/applications/pages/ui-builder/bonita-ui-builder-best-practices.adoc

@@ -21,5 +21,5 @@ xref:ui-builder/how-to-use-mutable-js-variable.adoc[[.card-title]#Use mutable JS
 
 [.card.card-index]
 --
-xref:ui-builder/how-to-retrieve-user-avatar.adoc[[.card-title]#Retrieve user avatar image# [.card-body.card-content-overflow]#pass:q[Discover how to fetch user avatar images and display them using the image widget.]#]
+xref:ui-builder/how-to-localize-your-application.adoc[[.card-title]#Localize your application for various languages# [.card-body.card-content-overflow]#pass:q[Discover how to make your application accessible in multiple languages.]#]
 --

modules/applications/pages/ui-builder/how-to-localize-your-application.adoc

@@ -0,0 +1,107 @@
+= Localize your application for various languages
+:page-aliases: applications:how-to-localize-your-application.adoc
+:description: Discover how to make your application accessible in multiple languages.
+
+{description}
+
+* Difficulty: beginner
+* Prerequisites: have an application on Bonita UI Builder
+
+Suppose you're creating an application and want to allow users to easily switch between several languages by choosing a language option.
+While UI Builder currently doesn't have a built-in feature for making an application multilingual, the steps below describe the recommended way to do so.
+
+
+== Example
+
+image:ui-builder/guides/localize-your-app.gif[localize-your-app]
+
+We will cover below all the steps shown in the gif above.
+
+=== 1 Design the application's interface
+* Drag and drop a `Select` widget onto your interface, name it `SelectLanguage`, and configure the Source Data property as follows:
+
+[source, JS]
+----
+[
+  {
+    "key": "English",
+    "value": "en"
+  },
+  {
+    "key": "Français",
+    "value": "fr"
+  },
+  {
+    "key": "Spanish",
+    "value": "es"
+  }
+]
+----
+
+* Now, drag and drop a `Text` widget onto your interface and add a sentence into its `Text` property.
+For example, `This is a sample application to demonstrate the possibility of making it available in multiple languages.`
+
+
+=== 2 Define JS objects
+* Go to the JS section, create a new JavaScript object, and name it `localization`.
+* In the `localization` file, define JavaScript objects for each language to correspond with the values set for the `SelectLanguage` widget. Include the words or sentences along with their translations as key-value pairs for all languages, as shown in the code snippet below:
+
+[source, JS]
+----
+export default {
+	translations: {
+		en: {
+			"This is a sample application to demonstrate the possibility of making it available in multiple languages.": "This is a sample application to demonstrate the posibility of making it available in multi-languages."
+		},
+		fr: {
+			"This is a sample application to demonstrate the possibility of making it available in multiple languages.": "Il s'agit d'un exemple d'application visant à démontrer la possibilité de la rendre disponible en plusieurs langues."
+		},
+		es: {
+			"This is a sample application to demonstrate the possibility of making it available in multiple languages.": "Esta es una aplicación de muestra para demostrar la posibilidad de hacerlo disponible en varios idiomas."
+		}
+	}
+}
+----
+
+
+[NOTE]
+====
+Ensure that all language keys match the values set in the `SelectLanguage` source data, such as en, fr, and es, etc.
+====
+
+* To keep the codebase organized, define another JavaScript object and name it `i18n`.
+* Copy and paste the JavaScript code blocks provided below:
+
+[source, JS]
+----
+export default {
+	languageKeys: {},
+	onLanguageChange() {
+		this.languageKeys = localization.translations[SelectLanguage.selectedOptionValue];
+	},
+	setLangugeKey() {
+		this.languageKeys = localization.translations["en"];
+		return this.languageKeys;
+	}
+}
+----
+
+This JavaScript module manages language translations using the `languageKeys` property. The `onLanguageChange()` method updates `languageKeys` based on the selected language, while `setLangugeKey()` sets it to the default English translations and returns the updated object.
+
+[NOTE]
+====
+Ensure that the `Run on page load` setting is enabled for the `setLanguageKey` function.
+====
+
+
+=== 3 Bind JS objects to the widgets
+* Come back to the UI section and select the `SelectLanguage` widget.
+* Set its `Label` to `{{i18n.languageKeys["Select language"]}}`.
+* In the Events property, set `{{i18n.onLanguageChange();}}` to invoke the function when the language changes.
+* Then, select the text widget and set the `Text` property to `{{i18n.languageKeys["This is a sample application to demonstrate the possibility of making it available in multiple languages."]}}`.
+
+
+[NOTE]
+====
+Since the goal of this example is to provide best practices for managing several languages, it does not address cookies. It is of course possible to define JS objects that manage cookies according to your needs.
+====