add "Translating external app" guide

Author: ivictbor

Changelog.md

@@ -5,9 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [v1.5.8] - next
+## [v1.5.9] - next
 
-# Added
+## [v1.5.8]
+
+### Added
 
 - Command to generate typescript models `npx -y adminforth generate-models --env-file=.env`
 - add i18n support: add vue-i18n to frontend and tr function to backend. This will allow to implement translation plugins
@@ -18,21 +20,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - make user menu switch shorter
 - next param support on login route (also preserve next param between login/signup navigation)
 
-# Fixed
-
-- favicon when using BaseURL
-
-
-# Improved
+### Improved
 
-- Added separate BeforeCreateSave function in types without oldRecord and make oldRecord Mandatory in existing BeforeSaveFunction
-  
+- Added separate BeforeCreateSave function in types without oldRecord and make oldRecord mandatory in existing BeforeSaveFunction
 - Added dataConnector: IAdminForthDataSourceConnectorBase; into IOperationalResource - for reusing connectors from users code
 
-# Fixed
+### Fixed
 
 - WS on base URL
-
+- favicon when using BaseURL
+- Mongo: fix search by strings with "+" and other special characters
+- mongo storing boolean as true/false now. Before it was 1/0 which broke compatibility with many other ORMs
 
 ## [v1.5.7] - 2024-12-09
 

adminforth/documentation/docs/tutorial/05-Plugins/10-i18n.md

@@ -418,4 +418,96 @@ import { admin } from '../index';
         ],
       }
 }
-```
+```
+
+## Translating external application
+
+You can use this module not only to translate Admin area of your application but also to translate other services of your application.
+This will allow you to reuse the same functionality and AI completion adapters for all your translations. For example in this app we 
+will consider that we have a Nuxt.js SEO-centric frontend which we want to translate with [vue-i18n](https://vue-i18n.intlify.dev/).
+
+To do it you need to use 2 function from the plugin. First at some step, e.g. CI pipeline you should get all translation strings from your external app (e.g. Nuxt.js frontend) and create an own rest API like `'/feed-nuxt-strings'`, this API might look like this
+
+For extracting 18n messages we use [vue-i18n-extract](https://github.com/Spittal/vue-i18n-extract) package. 
+You can add extract command to `package.json`:
+
+```json
+{
+  "scripts": {
+    "i18n:extract": "echo '{}' > i18n-empty.json && vue-i18n-extract report --vueFiles './src/**/*.?(js|vue)' --output ./i18n-messages.json --languageFiles 'i18n-empty.json' --add",
+    "i18n:feed-to-backoffice": "npm run i18n:extract && curl -X POST -H 'Content-Type: application/json' -d @i18n-messages.json http://adminforth:3000/feed-nuxt-strings"
+    ""
+  }
+}
+```
+
+Make sure to replace `adminforth:3000` with AdminForth API URL.
+
+
+```ts title="./index.ts"
+  app.get(`${ADMIN_BASE_URL}/feed-nuxt-strings`, 
+    async (req, res) => {
+      // req.body will be an array of objects like:
+      // [{
+      //    path: 'Login',
+      //    file: 'src/views/Login.vue:35',
+      // }]
+
+      const messagesForFeed = req.body.map((mk: any) => {
+        return {
+          en_string: mk.path,
+          source: mk.file,
+        };
+      });
+
+      admin.getPluginByClassName<I18nPlugin>('I18nPlugin').feedCategoryTranslations(
+        messagesForFeed,
+        'nextApp'
+      )
+
+      res.json({
+        ok: true
+      });
+    }
+  );
+
+```
+
+> 👆 This example method is just a stub, please make sure you not expose it to public or add some simple authorization on it,
+> otherwise someone might flood you with dump translations requests.
+
+Then in your Nuxt.js app you should call this API and store the strings in the same.
+
+Next part. When we will need translations on the nuxt instance, we should use [vue-i18n's lazy loading feature](https://vue-i18n.intlify.dev/guide/advanced/lazy):
+
+```typescript title="./your-buxt-app-source-file.ts"
+import { callAdminForthApi } from '@/utils';
+
+export async function loadLocaleMessages(i18n, locale) {
+  // load locale messages with dynamic import
+  const messages = await callAdminForthApi({
+    path: `/api/translations/?lang=${locale}`,
+    method: 'GET',
+  });
+
+  // set locale and locale message
+  i18n.global.setLocaleMessage(locale, messages.default)
+
+  return nextTick()
+}
+```
+
+See [vue-i18n's lazy loading feature](https://vue-i18n.intlify.dev/guide/advanced/lazy) to understand where better to call `loadLocaleMessages` function.
+
+Here is how API for messages will look:
+
+```ts title="./index.ts"
+app.get(`${ADMIN_BASE_URL}/api/translations/`, 
+  async (req, res) => {
+    const lang = req.query.lang;
+    const messages = await admin.getPluginByClassName<I18nPlugin>('I18nPlugin').getCategoryTranslations('nextApp', lang);
+    res.json(messages);
+  }
+);
+```
+

adminforth/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "adminforth",
-  "version": "1.5.8-next.27",
+  "version": "1.5.8",
   "description": "OpenSource Vue3 powered forth-generation admin panel",
   "main": "dist/index.js",
   "module": "dist/index.js",

adminforth/package.json

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [1.0.21] - next
 
+### Fixed
+- improve cache reset when editing messages manually
+
+### Added
+- Translating external app" feature by using feedCategoryTranslations
+
 ## [1.0.20]
 
 ### Fixed

adminforth/plugins/i18n/Changelog.md

@@ -251,18 +251,15 @@ export default class I18N extends AdminForthPlugin {
           if (lang === 'en') {
             continue;
           }
-          if (updates[this.trFieldNames[lang]]) {
+          if (updates[this.trFieldNames[lang]] !== undefined) {
             langsChanged.push(lang);
           }
         }
 
         // clear frontend cache for all langsChanged
         for (const lang of langsChanged) {
-          if (oldRecord[this.options.categoryFieldName] === 'frontend') {
-            this.cache.clear(`${this.resourceConfig.resourceId}:frontend:${lang}`);
-          } else {
-            this.cache.clear(`${this.resourceConfig.resourceId}:${oldRecord[this.options.categoryFieldName]}:${lang}:${oldRecord[this.enFieldName]}`);
-          }
+          this.cache.clear(`${this.resourceConfig.resourceId}:${oldRecord[this.options.categoryFieldName]}:${lang}`);
+          this.cache.clear(`${this.resourceConfig.resourceId}:${oldRecord[this.options.categoryFieldName]}:${lang}:${oldRecord[this.enFieldName]}`);
         }
         this.updateUntranslatedMenuBadge();
       }
@@ -274,11 +271,8 @@ export default class I18N extends AdminForthPlugin {
     resourceConfig.hooks.delete.afterSave.push(async ({ record }: { record: any }): Promise<{ ok: boolean, error?: string }> => {
       for (const lang of this.options.supportedLanguages) {
         // if frontend, clear frontend cache
-        if (record[this.options.categoryFieldName] === 'frontend') {
-          this.cache.clear(`${this.resourceConfig.resourceId}:frontend:${lang}`);
-        } else {
-          this.cache.clear(`${this.resourceConfig.resourceId}:${record[this.options.categoryFieldName]}:${lang}:${record[this.enFieldName]}`);
-        }
+        this.cache.clear(`${this.resourceConfig.resourceId}:${record[this.options.categoryFieldName]}:${lang}`);
+        this.cache.clear(`${this.resourceConfig.resourceId}:${record[this.options.categoryFieldName]}:${lang}:${record[this.enFieldName]}`);
       }
       this.updateUntranslatedMenuBadge();
       return { ok: true };
@@ -609,39 +603,16 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
       return;
     }
     // loop over missingKeys[i].path and add them to database if not exists
-    
-    const missingKeysDeduplicated = messages.missingKeys.reduce((acc: any[], missingKey: any) => {
-      if (!acc.find((a) => a.path === missingKey.path)) {
-        acc.push(missingKey);
-      }
-      return acc;
-    }, []);
-
-    await Promise.all(missingKeysDeduplicated.map(async (missingKey: any) => {
-      const key = missingKey.path;
-      const file = missingKey.file;
-      const category = 'frontend';
-      const exists = await adminforth.resource(this.resourceConfig.resourceId).count(Filters.EQ(this.enFieldName, key));
-      if (exists) {
-        return;
-      }
-      if (!key) {
-        throw new Error(`Faced an empty key in Fronted messages, file ${file}`);
-      }
-      const record = {
-        [this.enFieldName]: key,
-        [this.options.categoryFieldName]: category,
-        ...(this.options.sourceFieldName ? { [this.options.sourceFieldName]: file } : {}),
+    const messagesForFeed = messages.missingKeys.map((mk) => {
+      return {
+        en_string: mk.path,
+        source: mk.file,
       };
-      try {
-        await adminforth.resource(this.resourceConfig.resourceId).create(record);
-      } catch (e) {
-        console.error('🐛 Error creating record', e);
-      }
-    }));
+    });
 
-    // updateBadge
-    this.updateUntranslatedMenuBadge()
+    await this.feedCategoryTranslations(messagesForFeed, 'frontend')
+    
+    
   }
 
 
@@ -770,6 +741,60 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
     return `single`;
   }
 
+  async getCategoryTranslations(category: string, lang: string): Promise<Record<string, string>> {
+    const resource = this.adminforth.resource(this.resourceConfig.resourceId);
+    const cacheKey = `${this.resourceConfig.resourceId}:${category}:${lang}`;
+    const cached = await this.cache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+    const translations = {};
+    const allTranslations = await resource.list([Filters.EQ(this.options.categoryFieldName, category)]);
+    for (const tr of allTranslations) {
+      translations[tr[this.enFieldName]] = tr[this.trFieldNames[lang]];
+    }
+    await this.cache.set(cacheKey, translations);
+    return translations;
+  }
+
+  async feedCategoryTranslations(messages: {
+    en_string: string;
+    source: string;
+  }[], category: string): Promise<void> {
+    const adminforth = this.adminforth;
+    const missingKeysDeduplicated = messages.reduce((acc: any[], missingKey: any) => {
+      if (!acc.find((a) => a.en_string === missingKey.en_string)) {
+        acc.push(missingKey);
+      }
+      return acc;
+    }, []);
+
+    await Promise.all(missingKeysDeduplicated.map(async (missingKey: any) => {
+      const key = missingKey.en_string;
+      const source = missingKey.source;
+      const exists = await adminforth.resource(this.resourceConfig.resourceId).count(Filters.EQ(this.enFieldName, key));
+      if (exists) {
+        return;
+      }
+      if (!key) {
+        console.error(`Faced an empty key in feeding ${category} messages, source ${source}`);
+      }
+      const record = {
+        [this.enFieldName]: key,
+        [this.options.categoryFieldName]: category,
+        ...(this.options.sourceFieldName ? { [this.options.sourceFieldName]: source } : {}),
+      };
+      try {
+        await adminforth.resource(this.resourceConfig.resourceId).create(record);
+      } catch (e) {
+        console.error('🐛 Error creating record', e);
+      }
+    }));
+
+    // updateBadge
+    this.updateUntranslatedMenuBadge();
+  }
+
 
   setupEndpoints(server: IHttpServer) {
     server.endpoint({
@@ -780,18 +805,7 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
         const lang = query.lang;
 
         // form map of translations
-        const resource = this.adminforth.resource(this.resourceConfig.resourceId);
-        const cacheKey = `${this.resourceConfig.resourceId}:frontend:${lang}`;
-        const cached = await this.cache.get(cacheKey);
-        if (cached) {
-          return cached;
-        }
-        const translations = {};
-        const allTranslations = await resource.list([Filters.EQ(this.options.categoryFieldName, 'frontend')]);
-        for (const tr of allTranslations) {
-          translations[tr[this.enFieldName]] = tr[this.trFieldNames[lang]];
-        }
-        await this.cache.set(cacheKey, translations);
+        const translations = await this.getCategoryTranslations('frontend', lang);
         return translations;
 
       }

adminforth/plugins/i18n/index.ts

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/i18n",
-  "version": "1.0.20-next.0",
+  "version": "1.0.21-next.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

adminforth/plugins/i18n/package-lock.json

@@ -1,3 +1,8 @@
+## [v1.0.9]
+
+# Fixed
+- when user created normalize email to lowercase. This is not needed when right email validator is set on email field because
+it will not allow to create such email, but if user forgot to set it it might save situation 
 
 ## [v1.0.8]
 

adminforth/plugins/i18n/package.json

@@ -227,7 +227,9 @@ export default class OpenSignupPlugin extends AdminForthPlugin {
             }
           }
         }
-
+        
+        // This is not needed when right email validator is set on email field because
+        // it will not allow to create such email, but if user forgot to set it it might save situation 
         const normalizedEmail = email.toLowerCase();  // normalize email
 
         // first check again if email already exists