feat(dashboard): Support localization for dashboard extensions (#3962)

Author: michaelbromley

docs/docs/guides/extending-the-dashboard/localization/index.md

@@ -0,0 +1,94 @@
+---
+title: 'Localization'
+---
+
+:::note
+Support for localization of Dashboard extensions was added in v3.5.1
+:::
+
+The Dashboard uses [Lingui](https://lingui.dev/), which provides a powerful i18n solution for React:
+
+- ICU MessageFormat support
+- Automatic message extraction
+- TypeScript integration
+- Pluralization support
+- Compile-time optimization
+
+## Wrap your strings
+
+First you'll need to wrap any strings that need to be localized:
+
+```tsx
+import { Trans, useLingui } from '@lingui/react/macro';
+
+function MyComponent() {
+    const { t } = useLingui();
+
+    return (
+        <div>
+            <h1>
+                // highlight-next-line
+                <Trans>Welcome to Dashboard</Trans>
+            </h1>
+            // highlight-next-line
+            <p>{t`Click here to continue`}</p>
+        </div>
+    );
+}
+```
+
+You will mainly make use of the [Trans component](https://lingui.dev/ref/react#trans)
+and the [useLingui hook](https://lingui.dev/ref/react#uselingui).
+
+## Extract translations
+
+Create a `lingui.config.js` file in your project root, with references to any plugins that need to be localized:
+
+```js title="lingui.config.js
+import { defineConfig } from '@lingui/cli';
+
+export default defineConfig({
+    sourceLocale: 'en',
+    // Add any locales you wish to support
+    locales: ['en', 'de'],
+    catalogs: [
+        // For each plugin you want to localize, add a catalog entry
+        {
+            // This is the output location of the generated .po files
+            path: '<rootDir>/src/plugins/reviews/dashboard/i18n/{locale}',
+            // This is the pattern that tells Lingui which files to scan
+            // to extract translation strings
+            include: ['<rootDir>/src/plugins/reviews/dashboard/**'],
+        },
+    ],
+});
+```
+
+Then extract the translations:
+
+```bash
+npx lingui extract
+```
+
+This will output the given locale files in the directories specified in the config file above.
+In this case:
+
+```
+src/
+└── plugins/
+    └── reviews/
+        └── dashboard/
+            └── i18n/
+                ├── en.po
+                └── de.po
+```
+
+Since we set the "sourceLocale" to be "en", the `en.po` file will already be complete. You'll then need to
+open up the `de.po` file and add German translations for each of the strings, by filling out the empty `msgstr` values:
+
+```po title="de.po"
+#: test-plugins/reviews/dashboard/review-list.tsx:51
+msgid "Welcome to Dashboard"
+// highlight-next-line
+msgstr "Willkommen zum Dashboard"
+```

docs/sidebars.js

@@ -177,6 +177,7 @@ const sidebars = {
                 'guides/extending-the-dashboard/alerts/index',
                 'guides/extending-the-dashboard/data-fetching/index',
                 'guides/extending-the-dashboard/theming/index',
+                'guides/extending-the-dashboard/localization/index',
                 'guides/extending-the-dashboard/deployment/index',
                 'guides/extending-the-dashboard/tech-stack/index',
                 'guides/extending-the-dashboard/migration/index',

packages/dashboard/src/lib/lib/load-i18n-messages.ts

@@ -12,6 +12,9 @@ export async function loadI18nMessages(locale: string): Promise<Messages> {
     } else {
         // In dev mode we allow the dynamic import behaviour
         const { messages } = await import(`../../i18n/locales/${locale}.po`);
-        return messages;
+        const pluginTranslations = await import('virtual:plugin-translations');
+        const safeLocale = locale.replace(/-/g, '_');
+        const pluginTranslationsForLocale = pluginTranslations[safeLocale] ?? {};
+        return { ...messages, ...pluginTranslationsForLocale };
     }
 }

packages/dashboard/vite/utils/get-dashboard-paths.ts

@@ -0,0 +1,28 @@
+import path from 'path';
+
+import { PluginInfo } from '../types.js';
+
+/**
+ * Returns an array of the paths to plugins, based on the info provided by the ConfigLoaderApi.
+ */
+export function getDashboardPaths(pluginInfo: PluginInfo[]) {
+    return (
+        pluginInfo
+            ?.flatMap(({ dashboardEntryPath, sourcePluginPath, pluginPath }) => {
+                if (!dashboardEntryPath) {
+                    return [];
+                }
+                const sourcePaths = [];
+                if (sourcePluginPath) {
+                    sourcePaths.push(
+                        path.join(path.dirname(sourcePluginPath), path.dirname(dashboardEntryPath)),
+                    );
+                }
+                if (pluginPath) {
+                    sourcePaths.push(path.join(path.dirname(pluginPath), path.dirname(dashboardEntryPath)));
+                }
+                return sourcePaths;
+            })
+            .filter(x => x != null) ?? []
+    );
+}

packages/dashboard/vite/vite-plugin-tailwind-source.ts

@@ -1,7 +1,7 @@
-import path from 'path';
 import { Plugin } from 'vite';
 
 import { CompileResult } from './utils/compiler.js';
+import { getDashboardPaths } from './utils/get-dashboard-paths.js';
 import { ConfigLoaderApi, getConfigLoaderApi } from './vite-plugin-config-loader.js';
 
 /**
@@ -25,29 +25,7 @@ export function dashboardTailwindSourcePlugin(): Plugin {
                     loadVendureConfigResult = await configLoaderApi.getVendureConfig();
                 }
                 const { pluginInfo } = loadVendureConfigResult;
-                const dashboardExtensionDirs =
-                    pluginInfo
-                        ?.flatMap(({ dashboardEntryPath, sourcePluginPath, pluginPath }) => {
-                            if (!dashboardEntryPath) {
-                                return [];
-                            }
-                            const sourcePaths = [];
-                            if (sourcePluginPath) {
-                                sourcePaths.push(
-                                    path.join(
-                                        path.dirname(sourcePluginPath),
-                                        path.dirname(dashboardEntryPath),
-                                    ),
-                                );
-                            }
-                            if (pluginPath) {
-                                sourcePaths.push(
-                                    path.join(path.dirname(pluginPath), path.dirname(dashboardEntryPath)),
-                                );
-                            }
-                            return sourcePaths;
-                        })
-                        .filter(x => x != null) ?? [];
+                const dashboardExtensionDirs = getDashboardPaths(pluginInfo);
                 const sources = dashboardExtensionDirs
                     .map(extension => {
                         return `@source '${extension}';`;