RHIDP-8635-3 - Comprehensive documentation for developers on adding localization support to custom plugins (#1549)

Author: Gerry-Forde

assemblies/assembly-configuring-a-floating-action-button.adoc

@@ -8,4 +8,8 @@ You can use the floating action button plugin to configure any action as a float
 
 include::modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc[leveloffset=+1]
 
+// Localization
+include::modules/configuring-a-floating-action-button/con-localization-support-for-the-floating-action-button.adoc[leveloffset=+1]
+// END Localization
+
 include::modules/configuring-a-floating-action-button/ref-floating-action-button-parameters.adoc[leveloffset=+1]

assemblies/assembly-configuring-the-quickstarts.adoc

@@ -12,4 +12,4 @@ include::modules/configuring-the-quickstarts/proc-disabling-rhdh-quickstart.adoc
 
 include::modules/configuring-the-quickstarts/proc-starting-and-completing-modules-in-quickstarts.adoc[leveloffset=+1]
 
-include::modules/configuring-the-quickstarts/con-using-rbac-with-quickstarts.adoc[leveloffset=+1]
+include::modules/customizing-the-appearance/proc-enabling-localization-in-quickstarts.adoc[leveloffset=+1]

assemblies/assembly-customizing-the-appearance.adoc

@@ -32,6 +32,8 @@ include::modules/customizing-the-appearance/con-about-rhdh-sidebar-menuitems.ado
 
 include::modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+2]
 
+include::modules/customizing-the-appearance/proc-enabling-localization-in-sidebar-items.adoc[leveloffset=+2]
+
 include::modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc[leveloffset=+2]
 
 include::modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc[leveloffset=+2]

assemblies/assembly-localization-in-rhdh.adoc

@@ -0,0 +1,26 @@
+:_mod-docs-content-type: ASSEMBLY
+:context: assembly-localization-in-rhdh
+
+[id="assembly-localization-in-rhdh_{context}"]
+= Localization in {product}
+
+include::modules/customizing-the-appearance/proc-enabling-localization-in-rhdh.adoc[leveloffset=+1]
+
+include::modules/customizing-the-appearance/proc-select-rhdh-language.adoc[leveloffset=+1]
+
+include::modules/customizing-the-appearance/con-language-persistence.adoc[leveloffset=+2]
+
+// include::modules/customizing-the-appearance/proc-enabling-localization-in-quickstarts.adoc[leveloffset=+1]
+
+// include::modules/customizing-the-appearance/proc-enabling-localization-in-sidebar-items.adoc[leveloffset=+1]
+
+//include::modules/customizing-the-appearance/proc-enabling-localization-in-floating-action-button.adoc[leveloffset=+1]
+
+== Localization support for plugins
+
+include::modules/customizing-the-appearance/proc-overriding-translations.adoc[leveloffset=+2]
+
+include::modules/customizing-the-appearance/ref-best-practices-for-localization.adoc[leveloffset=+2]
+
+include::modules/customizing-the-appearance/proc-adding-localization-to-custom-plugins.adoc[leveloffset=+2]
+

images/rhdh/customize-language-dropdown.png

@@ -0,0 +1,60 @@
+[id="proc-enabling-localization-in-floating-action-button_{context}"]
+= Enabling floating action button localization in {product-very-short}
+
+You can enable translation key support for floating action buttons, so that users can onboard in their preferred language. In {product-short}, all existing and newly created floating action buttons support localization using dedicated translation keys. 
+
+The Global Floating Action Button plugin supports internationalization (i18n) through translation keys. You can use `labelKey` and `toolTipKey` properties to provide translation keys instead of static text.
+
+The plugin provides the following built-in translation keys organized under the `fab` namespace:
+
+* `fab.create.label` - "Create"
+* `fab.create.tooltip` - "Create entity"
+* `fab.docs.label` - "Docs"
+* `fab.docs.tooltip` - "Documentation"
+* `fab.apis.label` - "APIs"
+* `fab.apis.tooltip` - "API Documentation"
+* `fab.github.label` - "GitHub"
+* `fab.github.tooltip` - "GitHub Repository"
+* `fab.bulkImport.label` - "Bulk Import"
+* `fab.bulkImport.tooltip` - "Register multiple repositories in bulk"
+* `fab.quay.label` - "Quay"
+* `fab.quay.tooltip` - "Quay Container Registry"
+
+The plugin includes translations for the following supported languages:
+
+* English (default)
+// * German (de)
+* French (fr)
+// * Spanish (es)
+
+// [NOTE]
+// ====
+// To add localization support for a new floating action button item, you can add any arbitrary key name for the `labelKey` and `toolTipKey` properties and provide corresponding translations for those keys.
+
+// If you add a new floating action button item, you can add localization support by adding an arbitary label key and tool tip key 
+
+// ====
+
+To ensure backward compatibility while providing translation support when available, the following order is used to resolve string translations:
+
+. If the `labelKey` is provided, the plugin will attempt to resolve the translation key
+. If the translation key is found, it will be used as the label
+. If the translation key is not found, the plugin will fall back to the label property
+
+[NOTE]
+====
+The same logic applies to `toolTipKey` and `toolTip`.
+====
+
+== Internal translation implementation
+The plugin uses a centralized translation system where:
+
+* The `useTranslation()` hook is called in components that render floating action buttons to ensure proper translation context initialization
+* The translation function (`t`) is passed down to child components that need to resolve translation keys
+* This internal architecture prevents infinite re-render loops and ensures stable component rendering
+* All components that use `CustomFab` must provide the translation function as a prop
+
+[NOTE]
+====
+When extending or modifying the plugin components, ensure that the `useTranslation()` hook is called in parent components and the `t` prop is passed to `CustomFab` instances to maintain proper translation functionality and prevent rendering issues.
+====

modules/configuring-a-floating-action-button/con-localization-support-for-the-floating-action-button.adoc

@@ -203,3 +203,43 @@ To configure a floating action button as a dynamic plugin, complete any of the f
                 text: Bulk import
 ----
 `frontend:mountPoints:importName`:: Enter the import name with an associated component to the mount point.
+
+= Translation support
+The Global Floating Action Button plugin supports internationalization (i18n) through translation keys. You can use `labelKey` and `toolTipKey` properties to provide translation keys instead of static text.
+
+Example for using translation keys in dynamic configuration:
+[source,yaml]
+----
+- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button
+  disabled: false
+  pluginConfig:
+    dynamicPlugins:
+      frontend:
+        red-hat-developer-hub.backstage-plugin-global-floating-action-button:
+          translationResources:
+            - importName: globalFloatingActionButtonTranslations
+              ref: globalFloatingActionButtonTranslationRef
+          mountPoints:
+            - mountPoint: application/listener
+              importName: DynamicGlobalFloatingActionButton
+            - mountPoint: global.floatingactionbutton/config
+              importName: NullComponent
+              config:
+                icon: github
+                label: 'GitHub' # Fallback text
+                labelKey: 'fab.github.label' # Translation key
+                toolTip: 'GitHub Repository' # Fallback text
+                toolTipKey: 'fab.github.tooltip' # Translation key
+                to: https://github.com/redhat-developer/rhdh-plugins
+            - mountPoint: global.floatingactionbutton/config
+              importName: NullComponent
+              config:
+                color: 'success'
+                icon: search
+                label: 'Create' # Fallback text
+                labelKey: 'fab.create.label' # Translation key
+                toolTip: 'Create entity' # Fallback text
+                toolTipKey: 'fab.create.tooltip' # Translation key
+                to: '/create'
+                showLabel: true
+----

modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc

@@ -21,6 +21,12 @@ Use the parameters as shown in the following table to configure your floating ac
 | Not applicable
 | Yes
 
+| `labelKey`
+| Translation key for the label. If provided, will be used instead of label when translations are available.
+| `String`
+| Not applicable
+| No
+
 | `icon`
 | Icon of the floating action button. Recommended to use filled icons from the link:https://fonts.google.com/icons[Material Design library]. You can also use an svg icon. For example: `<svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#e8eaed"><g><rect fill="none" height="24" width="24"/></g><g><path d="M11,7L9.6,8.4l2.6,2.6H2v2h10.2l-2.6,2.6L11,17l5-5L11,7z M20,19h-8v2h8c1.1,0,2-0.9,2-2V5c0-1.1-0.9-2-2-2h-8v2h8V19z"/></g></svg>`
 | `String`, `React.ReactElement`, `SVG image icon`, `HTML image icon`
@@ -63,6 +69,12 @@ Use the parameters as shown in the following table to configure your floating ac
 | Not applicable
 | No
 
+| `toolTipKey`
+| Translation key for the tooltip. If provided, will be used instead of toolTip when translations are available.
+| `String`
+| Not applicable
+| No
+
 | `priority`
 | Order of the floating action buttons displayed in the submenu. A larger value means higher priority.
 | `number`

modules/configuring-a-floating-action-button/ref-floating-action-button-parameters.adoc

@@ -0,0 +1,27 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con-language-persistence_{context}"]
+= Language persistence
+
+When you change the language in the UI, your preference is saved to storage. On next login or refresh, your chosen language setting is restored. Guest users cannot persist language preferences.
+
+Default language selection uses the following priority order:
+
+. *Browser language priority*: The system first checks the user's browser language preferences to provide a personalized experience.
+
+. *Configuration priority*: If no browser language matches the supported locales, the `defaultLocale` from the `i18n` configuration is used as a fallback.
+
+. *Fallback priority*: If neither browser preferences nor configuration provide a match, defaults to `en`.
+
+{product} automatically saves and restores user language settings across browser sessions. This feature is enabled by default and uses database storage. To opt-out and use browser storage instead, add the following to your `{my-app-config-file}` configuration file:
+[source,yaml,subs="+quotes"]
+----
+userSettings:
+  persistence: browser 
+----
+
+where:
+
+userSettings:persistence:: 
+Enter `browser` to opt-out and use browser local storage. Optionally, set this value to `database` to persist across browsers and devices. This is the default setting and does not require this configuration to be set.
+