RHIDP-8635-1-1-8 - Comprehensive documentation for developers on adding localization support to custom plugins

artifacts/attributes.adoc

@@ -53,8 +53,8 @@
 :odf-name: OpenShift Data Foundation
 :osd-brand-name: Red Hat OpenShift Dedicated
 :osd-short: OpenShift Dedicated
-:rcs-name: Road-Core Service
-:rcs-short: RCS
+:lcs-name: Lightspeed Core Service
+:lcs-short: LCS
 :rhacs-brand-name: Red Hat Advanced Cluster Security
 :rhacs-short: Advanced Cluster Security
 :rhacs-very-short: ACS
@@ -87,8 +87,8 @@
 :eks-brand-name: Amazon Elastic Kubernetes Service
 :eks-name: Elastic Kubernetes Service
 :eks-short: EKS
-:gcp-brand-name: Google Cloud Platform
-:gcp-short: GCP
+:gcp-brand-name: Google Cloud
+:gcp-short: Google Cloud
 :gke-brand-name: Google Kubernetes Engine
 :gke-short: GKE
 

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-developer-lightspeed.adoc

@@ -4,9 +4,7 @@
 [id="{context}"]
 = Customizing {ls-short}
 
-You can customize {ls-short} functionalities, such as, question validation, gathering feedback, and storing chat history in PostgreSQL.
-
-include::modules/developer-lightspeed/proc-using-question-validation.adoc[leveloffset=+1]
+You can customize {ls-short} functionalities such as gathering feedback, storing chat history in PostgreSQL, and {model-context-protocol-link}#proc-configure-mcp-tools-for-developer-lightspeed_assembly-model-context-protocol-tools[configuring Model Context Protocol (MCP) tools].
 
 include::modules/developer-lightspeed/proc-gathering-feedback.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-developer-lightspeed.adoc

@@ -8,7 +8,7 @@ include::modules/developer-lightspeed/con-about-developer-lightspeed.adoc[levelo
 
 include::modules/developer-lightspeed/con-supported-architecture.adoc[leveloffset=+1]
 
-include::modules/developer-lightspeed/con-about-road-core-service.adoc[leveloffset=+2]
+include::modules/developer-lightspeed/con-about-lightspeed-stack-and-llama-stack.adoc[leveloffset=+2]
 
 include::modules/developer-lightspeed/con-rag-embeddings.adoc[leveloffset=+1]
 

assemblies/assembly-install-rhdh-osd-gcp.adoc

@@ -4,7 +4,7 @@
 = Installing {product} on {osd-short} on {gcp-brand-name}
 :context: assembly-install-rhdh-osd-gcp
 
-You can install {product-short} on {osd-short} on {gcp-brand-name} ({gcp-short}) using one of the following methods:
+You can install {product-short} on {osd-short} on {gcp-brand-name} using one of the following methods:
 
 * The {product} Operator
 * The {product} Helm chart

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]
+

assemblies/assembly-model-context-protocol-tools.adoc

@@ -12,8 +12,6 @@ include::modules/model-context-protocol-tools/proc-configuring-model-context-pro
 
 include::modules/model-context-protocol-tools/proc-configuring-mcp-clients-to-access-the-rhdh-server.adoc[leveloffset=+2]
 
-include::modules/model-context-protocol-tools/proc-configuring-mcp-tools-for-developer-lightspeed.adoc[leveloffset=+1]
-
 include::assembly-using-the-mcp-tools-to-access-data.adoc[leveloffset=+1]
 
 include::assembly-troubleshooting-mcp-server-and-client-problems.adoc[leveloffset=+1]

assemblies/assembly-orchestrator-rhdh.adoc

@@ -24,7 +24,6 @@ To start using Orchestrator in {product-very-short}, you must:
 
 * Install the required infrastructure components, such as Red Hat OpenShift Serverless Operator, Knative Serving, Knative Eventing, and OpenShift Serverless Logic Operator
 * Configure your {product-custom-resource-type} custom resource (CR) or Helm values file for Orchestrator
-* Import the Orchestrator software templates into the {product} catalog
 
 // orchestrator architecture
 include::modules/orchestrator/con-architecture-overview.adoc[leveloffset=+1]
@@ -48,4 +47,4 @@ include::modules/orchestrator/proc-manual-install-components-orchestrator-plugin
 include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+2]
 
 // best practices when creating workflows
-include::modules/orchestrator/ref-best-practices-for-creating-workflows.adoc[leveloffset=+1]
+include::modules/orchestrator/ref-best-practices-for-creating-workflows.adoc[leveloffset=+1]

assemblies/assembly-using-developer-lightspeed.adoc

@@ -13,6 +13,15 @@ endif::[]
 
 {ls-brand-name} is designed to support you when performing various tasks during your development workflow.
 
+[NOTE]
+====
+The `Question Validation` feature is enabled by default if you are using the `quay.io/redhat-ai-dev/llama-stack` image without overriding the `run.yaml` configuration file in the image. To disable `Question Validation`, you must mount a `run.yaml` file to the container with the following sections removed:
+
+* `Safety`
+* `Shields`
+* `External_providers_dir` set to `null` 
+====
+
 With `Question Validation` enabled, you can ask {ls-short} the following types of questions:
 
 * “Tell me about {product}.”

modules/about/ref-rhdh-sizing.adoc

@@ -3,7 +3,9 @@
 [id="rhdh-sizing_{context}"]
 = Sizing requirements for {product}
 
-Scaling the {product} requires significant resource allocation. The following table lists the sizing requirements for installing and running {product}, including {product-short} application, database components, and Operator.
+Learn about sizing requirements for {product}.
+Table 1 lists the sizing requirements for installing and running {product}, including {product-short} application, database components, and Operator.
+Table 2 lists recommended sizing requirements for {product-docs-link}/html-single/configuring_red_hat_developer_hub/index#configuring-external-postgresql-databases[external PostgreSQL deployment] based on the deployment scale.
 
 .Recommended sizing for running {product}
 [cols="25%,25%,25%,25%", frame="all", options="header"]
@@ -33,3 +35,53 @@ Scaling the {product} requires significant resource allocation. The following ta
 |3 or more
 |1 or more
 |===
+
+.Recommended sizing for external PostgreSQL deployments with {product}
+[cols="25%,25%,25%,25%,25%", frame="all", options="header"]
+|===
+|Sizing legend
+|Small-scale
+|Mid-scale
+|Large-scale
+|Enterprise-scale
+
+|Application usage
+|up to 5 thousand entities, up to 50 concurrent users
+|5–20 thousand entities, 50–150 concurrent users
+|20–50 thousand entities, 150–400 concurrent users
+|50–150 thousand entities, 400–800 concurrent users
+
+|vCPU
+|2
+|4
+|8
+|16
+
+|Memory
+|8 GiB
+|16 GiB
+|32 GiB
+|64 GiB
+
+|Storage
+|50 GiB
+|100 GiB
+|200 GiB
+|500 GiB
+
+|Number of replicas
+|1
+|2
+|2-3
+|3+
+
+|PostgreSQL Database HA
+|1 primary
+|1 primary, 1 standby
+|1 primary, 1 synchronous standby
+|1 primary, 1 synchronous standby, 1 asynchronous replica
+|===
+
+
+
+

modules/authorization/proc-configuring-the-RBAC-backend-plugin.adoc

@@ -6,7 +6,7 @@
 You can configure the RBAC backend plugin by updating the `{my-app-config-file}` file to enable the permission framework.
 
 .Prerequisites
-* You have installed the `@janus-idp/backstage-plugin-rbac` plugin in {product-short}. For more information, see {configuring-dynamic-plugins-book-link}[{configuring-dynamic-plugins-book-title}].
+* You have installed the `@backstage-community/plugin-rbac` plugin in {product-short}. For more information, see {configuring-dynamic-plugins-book-link}[{configuring-dynamic-plugins-book-title}].
 
 .Procedure
 * Update the `{my-app-config-file}` file to enable the permission framework as shown:

modules/authorization/proc-setting-up-the-guest-authentication-provider.adoc

@@ -6,7 +6,7 @@
 You can enable guest authentication and use it alongside the RBAC frontend plugin.
 
 .Prerequisites
-* You have installed the `@janus-idp/backstage-plugin-rbac` plugin in {product-short}. For more information, see {configuring-dynamic-plugins-book-link}[{configuring-dynamic-plugins-book-title}].
+* You have installed the `@backstage-community/plugin-rbac` plugin in {product-short}. For more information, see {configuring-dynamic-plugins-book-link}[{configuring-dynamic-plugins-book-title}].
 
 .Procedure
 

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

@@ -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/proc-configuring-floating-action-button-as-a-dynamic-plugin.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/ref-floating-action-button-parameters.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-external-databases/proc-configuring-postgresql-instance-using-helm.adoc

@@ -7,6 +7,7 @@ You can configure an external PostgreSQL instance by using the Helm Chart. By de
 
 .Prerequisites
 
+* You meet the {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for external PostgreSQL deployments].
 * You are using a supported version of PostgreSQL. For more information, see the link:https://access.redhat.com/support/policy/updates/developerhub[Product life cycle page].
 * You have the following details:
 ** `db-host`: Denotes your PostgreSQL instance Domain Name System (DNS) or IP address

modules/configuring-external-databases/proc-configuring-postgresql-instance-using-the-operator.adoc

@@ -7,6 +7,7 @@ You can configure an external PostgreSQL instance using the {product} Operator.
 
 .Prerequisites
 
+* You meet the {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for external PostgreSQL deployments].
 * You are using a supported version of PostgreSQL. For more information, see the link:https://access.redhat.com/support/policy/updates/developerhub[Product life cycle page].
 * You have the following details:
 ** `db-host`: Denotes your PostgreSQL instance Domain Name System (DNS) or IP address