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

assemblies/assembly-localization-in-rhdh.adoc

@@ -0,0 +1,19 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[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-overriding-translations.adoc[leveloffset=+2]
+
+include::modules/customizing-the-appearance/proc-select-rhdh-language.adoc[leveloffset=+1]
+
+include::modules/customizing-the-appearance/con-language-persistence.adoc[leveloffset=+2]
+
+== Localization support for custom plugins
+
+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]
+

modules/customizing-the-appearance/con-language-persistence.adoc

@@ -0,0 +1,23 @@
+:_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`.
+
+Red Hat Developer Hub 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 # <1>
+----
+<1> To opt-out and use browser local storage, set this value to `browser`. Optionally, set this value to `database` to persist across browsers and devices. This the default setting and does not require this configuration to be set.
+

modules/customizing-the-appearance/proc-adding-localization-to-custom-plugins.adoc

@@ -0,0 +1,252 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-adding-localization-to-custom-plugins_{context}"]
+= Implementing localization support for your custom plugins
+You can implement localization support in your custom {product-very-short} plugins so that your plugins are accessible to a diverse, international user base and follow recommended best practices.
+
+.Procedure
+. Create the following translation files in your plugin's `src/translations/` directory:
++
+.`src/translations/ref.ts` English reference
+[source,json]
+----
+import { createTranslationRef } from "@backstage/core-plugin-api/alpha";
+
+export const myPluginMessages = {
+ page: {
+   title: "My Plugin",
+   subtitle: "Plugin description",
+ },
+ common: {
+   exportCSV: "Export CSV",
+   noResults: "No results found",
+ },
+ table: {
+   headers: {
+     name: "Name",
+     count: "Count",
+   },
+ },
+};
+
+export const myPluginTranslationRef = createTranslationRef({
+ id: "plugin.my-plugin",
+ messages: myPluginMessages,
+});
+----
++
+.`src/translations/de.ts` German translation
+[source,json]
+----
+import { createTranslationMessages } from "@backstage/core-plugin-api/alpha";
+import { myPluginTranslationRef } from "./ref";
+
+const myPluginTranslationDe = createTranslationMessages({
+ ref: myPluginTranslationRef,
+ messages: {
+   "page.title": "Mein Plugin",
+   "page.subtitle": "Plugin-Beschreibung",
+   "common.exportCSV": "CSV exportieren",
+   "common.noResults": "Keine Ergebnisse gefunden",
+   "table.headers.name": "Name",
+   "table.headers.count": "Anzahl",
+ },
+});
+
+export default myPluginTranslationDe;
+----
++
+.`src/translations/fr.ts` French translation
+[source,json]
+----
+import { createTranslationMessages } from "@backstage/core-plugin-api/alpha";
+import { myPluginTranslationRef } from "./ref";
+
+const myPluginTranslationFr = createTranslationMessages({
+ ref: myPluginTranslationRef,
+ messages: {
+   "page.title": "Mon Plugin",
+   "page.subtitle": "Description du plugin",
+   "common.exportCSV": "Exporter CSV",
+   "common.noResults": "Aucun résultat trouvé",
+   "table.headers.name": "Nom",
+   "table.headers.count": "Nombre",
+ },
+});
+
+export default myPluginTranslationFr;
+----
++
+.`src/translations/index.ts` Translation resource
+[source,json]
+----
+import { createTranslationResource } from "@backstage/core-plugin-api/alpha";
+import { myPluginTranslationRef } from "./ref";
+
+export const myPluginTranslations = createTranslationResource({
+ ref: myPluginTranslationRef,
+ translations: {
+   de: () => import("./de"),
+   fr: () => import("./fr"),
+ },
+});
+
+export { myPluginTranslationRef };
+----
+
+. Create translation hooks file, as follows:
++
+.`src/hooks/useTranslation.ts` Translation hooks
+[source,json]
+----
+import { useTranslationRef } from "@backstage/core-plugin-api/alpha";
+import { myPluginTranslationRef } from "../translations";
+
+export const useTranslation = () => useTranslationRef(myPluginTranslationRef);
+----
+
+. Update your plugin components to replace hardcoded strings with translation calls. For example:
++
+.Before (hardcoded):
+[source,json]
+----
+const MyComponent = () => {
+ return (
+   <div>
+     <h1>My Plugin</h1>
+     <button>Export CSV</button>
+   </div>
+ );
+};
+----
++
+.After (translated):
+[source,json]
+----
+import { useTranslation } from '../hooks/useTranslation';
+
+const MyComponent = () => {
+ const { t } = useTranslation();
+
+ return (
+   <div>
+     <h1>{t('page.title')}</h1>
+     <button>{t('common.exportCSV')}</button>
+   </div>
+ );
+};
+----
+
+. (Optional) If your content contains variables, use interpolation:
++
+[source,json]
+----
+// In your translation files
+'table.pagination.topN': 'Top {{count}} items'
+
+// In your component
+const { t } = useTranslation();
+const message = t('table.pagination.topN', { count: '10' });
+----
+
+. (Optional) If your content contains dynamic translation keys (for example, from your plugin configuration):
++
+[source,json]
+----
+// Configuration object with translation keys
+const CARD_CONFIGS = [
+ { id: 'overview', titleKey: 'cards.overview.title' },
+ { id: 'details', titleKey: 'cards.details.title' },
+ { id: 'settings', titleKey: 'cards.settings.title' },
+];
+
+// In your component
+const { t } = useTranslation();
+
+const CardComponent = ({ config }) => {
+ return (
+   <div>
+     <h2>{t(config.titleKey as any)}</h2>
+     {/* Use 'as any' for dynamic keys */}
+   </div>
+ );
+};
+----
+
+. Export the translation resources
++
+[source,json]
+.`src/alpha.ts` file fragment
+----
+// Export your plugin
+export { myPlugin } from "./plugin";
+
+// Export translation resources for RHDH
+export { myPluginTranslations, myPluginTranslationRef } from "./translations";
+----
+
+. Update your `dynamic-plugins.default.yaml` file, as follows:
++
+[source,json]
+.`dynamic-plugins.default.yaml` file fragment
+----
+backstage-community.plugin-my-plugin:
+ translationResources:
+   - importName: myPluginTranslations
+     ref: myPluginTranslationRef
+     module: Alpha
+----
+
+.Verification
+To verify your translations, create a test mock file. For example:
+
+.`src/test-utils/mockTranslations.ts` Test mock file
+[source,json]
+----
+import { myPluginMessages } from "../translations/ref";
+
+function flattenMessages(obj: any, prefix = ""): Record<string, string> {
+ const flattened: Record<string, string> = {};
+ for (const key in obj) {
+   if (obj.hasOwnProperty(key)) {
+     const value = obj[key];
+     const newKey = prefix ? `${prefix}.${key}` : key;
+     if (typeof value === "object" && value !== null) {
+       Object.assign(flattened, flattenMessages(value, newKey));
+     } else {
+       flattened[newKey] = value;
+     }
+   }
+ }
+ return flattened;
+}
+
+const flattenedMessages = flattenMessages(myPluginMessages);
+
+export const mockT = (key: string, params?: any) => {
+ let message = flattenedMessages[key] || key;
+ if (params) {
+   for (const [paramKey, paramValue] of Object.entries(params)) {
+     message = message.replace(
+       new RegExp(`{{${paramKey}}}`, "g"),
+       String(paramValue),
+     );
+   }
+ }
+ return message;
+};
+
+export const mockUseTranslation = () => ({ t: mockT });
+----
+
+.Update your tests
+[source,json]
+----
+import { mockUseTranslation } from "../test-utils/mockTranslations";
+
+jest.mock("../hooks/useTranslation", () => ({
+ useTranslation: mockUseTranslation,
+}));
+
+// Your test code...
+----

modules/customizing-the-appearance/proc-customize-rhdh-language.adoc

@@ -0,0 +1,26 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-customize-rhdh-language_{context}"]
+= Customizing the language for your {product-short} instance
+
+The language settings of {product-very-short} use English by default. You can choose to use one of the following languages instead.
+
+.Supported languages
+* English
+* French
+
+[NOTE]
+====
+English and French are the supported languages in {product-very-short} 1.8. You can add other languages in the the `i18n` section of your `{my-app-config-file}` configuration file.
+====
+
+.Prerequisites
+
+* You are logged in to the {product-short} web console.
+
+.Procedure
+
+. From the {product-short} web console, click *Settings*.
+. From the *Appearance* panel, click the language dropdown to select your language of choice.
++
+image::rhdh/customize-language-dropdown.png[]

modules/customizing-the-appearance/proc-enabling-localization-in-rhdh.adoc

@@ -0,0 +1,26 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-enabling-localization-in-rhdh_{context}"]
+= Enabling the localization framework in {product-short}
+Enabling localization enhances accessibility, improves the user experience for a global audience, and assists organizations in meeting language requirements in specific regions.
+
+The language settings of {product} ({product-very-short}) use English by default. In {product-very-short} {product-version}, you can choose to use one of the following supported languages:
+
+* English (en)
+* French (fr)
+
+.Prerequisites
+
+.Procedure
+. To enable the localization framework in your {product-very-short} application, add the `i18n` section to your custom {product-short} `{my-app-config-file}` configuration file:
++
+[id=i18n]
+.`{my-app-config-file}` fragment with localization `i18n` fields
+[source,yaml,subs="+quotes"]
+----
+i18n:
+  locales: # List of supported locales. Must include `en`, otherwise the translation framework will fail to load.
+    - en
+    - fr
+  defaultLocale: en # Optional. Defaults to `en` if not specified.
+----