finalize i18n plugin, pluralization for i18n

Author: ivictbor

Changelog.md

@@ -11,6 +11,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - 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
+- badgeTooltip - now you can add a tooltip to the badge to explain what it means
+- ability to authorize not only subscription on websocket but filter out whom users message will be published (updated doc)
+- added ability to refresh menu item badge from the backend using websocket publish
 
 # Improved
 

adminforth/dataConnectors/postgres.ts

@@ -27,7 +27,7 @@ class PostgresConnector extends AdminForthBaseConnector implements IAdminForthDa
 
     OperatorsMap = {
         [AdminForthFilterOperators.EQ]: '=',
-        [AdminForthFilterOperators.NE]: '!=',
+        [AdminForthFilterOperators.NE]: 'IS DISTINCT FROM',
         [AdminForthFilterOperators.GT]: '>',
         [AdminForthFilterOperators.LT]: '<',
         [AdminForthFilterOperators.GTE]: '>=',
@@ -215,6 +215,7 @@ class PostgresConnector extends AdminForthBaseConnector implements IAdminForthDa
             totalCounter += 1;
         }
 
+
         if (fieldData._underlineType == 'uuid') {
           field = `cast("${field}" as text)`
         } else { 
@@ -232,6 +233,8 @@ class PostgresConnector extends AdminForthBaseConnector implements IAdminForthDa
           filterValues.push(`%${v}%`);
         } else if (f.operator == AdminForthFilterOperators.IN || f.operator == AdminForthFilterOperators.NIN) {
           filterValues.push(...v);
+
+        
         } else {
           filterValues.push(v);
         }

adminforth/documentation/docs/tutorial/03-Customization/06-customPages.md

@@ -38,15 +38,15 @@ Create a Vue component in the `custom` directory of your project, e.g. `Dashboar
 <template>
   <div class="px-4 py-8 bg-blue-50 dark:bg-gray-900 dark:shadow-none min-h-screen">
     <h1 class="mb-4 text-xl font-extrabold text-gray-900 dark:text-white md:text-2xl lg:text-3xl"><span
-        class="text-transparent bg-clip-text bg-gradient-to-r to-emerald-600 from-sky-400">Apartments</span>
+        class="text-transparent bg-clip-text bg-gradient-to-r to-emerald-600 from-sky-400">{{ $t('Apartments') }}</span>
       Statistics.</h1>
 
     <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
       <div class="max-w-md w-full bg-white rounded-lg shadow dark:bg-gray-800 p-4 md:p-6" v-if="data">
         <div class="flex justify-between">
           <div>
             <h5 class="leading-none text-3xl font-bold text-gray-900 dark:text-white pb-2">{{ data.totalAparts }}</h5>
-            <p class="text-base font-normal text-gray-500 dark:text-gray-400">Apartments last 7 days</p>
+            <p class="text-base font-normal text-gray-500 dark:text-gray-400">{{ $t('Apartment last 7 days | Apartments last 7 days', data.totalAparts) }}</p>
           </div>
 
         </div>
@@ -58,15 +58,15 @@ Create a Vue component in the `custom` directory of your project, e.g. `Dashboar
 
         <div class="grid grid-cols-2 py-3">
           <dl>
-            <dt class="text-base font-normal text-gray-500 dark:text-gray-400 pb-1">Listed price</dt>
+            <dt class="text-base font-normal text-gray-500 dark:text-gray-400 pb-1">{{ $t('Listed price') }}</dt>
             <dd class="leading-none text-xl font-bold text-green-500 dark:text-green-400">{{
         new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(
           data.totalListedPrice,
         ) }}
             </dd>
           </dl>
           <dl>
-            <dt class="text-base font-normal text-gray-500 dark:text-gray-400 pb-1">Unlisted price</dt>
+            <dt class="text-base font-normal text-gray-500 dark:text-gray-400 pb-1">{{ $t('Unlisted price') }}</dt>
             <dd class="leading-none text-xl font-bold text-red-600 dark:text-red-500">{{
         new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(
           data.totalUnlistedPrice,
@@ -83,7 +83,7 @@ Create a Vue component in the `custom` directory of your project, e.g. `Dashboar
         <div class="flex justify-between mb-5">
           <div>
             <p class="text-base font-normal text-gray-500 dark:text-gray-400">
-              Unlisted vs Listed price
+              {{ $t('Unlisted vs Listed price') }}
             </p>
           </div>
         </div>

adminforth/documentation/docs/tutorial/03-Customization/10-menuConfiguration.md

@@ -151,10 +151,11 @@ You can add a badge near the menu item title (e.g. to get count of unread messag
       label: 'Posts',
       icon: 'flowbite:book-open-outline',
       resourceId: 'posts',
-      badge:  async (adminUser: AdminUser) => {
+      badge: async (adminUser: AdminUser) => {
         return 10
       },
-      ...,
+      badgeTooltip: 'New posts',  // explain user what this badge means
+      ...
     },
   ],
   ...
@@ -163,8 +164,64 @@ You can add a badge near the menu item title (e.g. to get count of unread messag
 
 Badge function is async, but all badges are loaded in "lazy" to not block the menu rendering.
 
-To refresh all badges in menu from the frontend component you can use the following code:
+### Refreshing the badges
 
+
+Most times you need to refresh the badge from some backend API or hook. To do this you can do next:
+
+1) Add `itemId` to menu item to identify it:
+
+```ts title='./index.ts'
+{
+  ...
+  menu: [
+    {
+      label: 'Posts',
+      icon: 'flowbite:book-open-outline',
+      resourceId: 'posts',
+//diff-add
+      itemId: 'postsMenuItem',
+      badge: async (adminUser: AdminUser) => {
+        return 10
+      },
+      badgeTooltip: 'Unverified posts',  // explain user what this badge means
+      ...
+    },
+  ],
+  ...
+}
 ```
+
+2) On backend point where you need to refresh the badge, you can publish a message to the websocket topic:
+
+```ts title='./index.ts'
+{
+  resourceId: 'posts',
+  table: 'posts',
+  hooks: {
+    edit: {
+//diff-add
+      afterSave: async ({ record, adminUser, resource, adminforth }) => {
+//diff-add
+        const newCount = await adminforth.resource('posts').count(Filters.EQ('verified', false));
+//diff-add
+        adminforth.websocket.publish(`/opentopic/update-menu-badge/postsMenuItem`, { badge: newCount });
+//diff-add
+        return { ok: true }
+//diff-add
+      }
+    }
+  }
+}
+```
+
+
+> 👆 Please note that any `/opentopic/` publish can be listened by anyone without authorization. If count published in this channel might be
+> a subject of security or privacy concerns, you should add [publish authorization](/docs/tutorial/Customization/websocket/#publish-authorization) to the topic.
+
+More rare case when you need to refresh menu item from the frontend component. You can achieve this by calling the next method:
+
+```typescript
 window.adminforth.menu.refreshMenuBadges()
-```
+```
+

adminforth/documentation/docs/tutorial/03-Customization/15-websocket.md

@@ -162,9 +162,13 @@ const admin = new AdminForth({
 
 ```
 
-### Authorization
+### Subscribing authorization
 
-Currently, any user can subscribe to the any topic. Though topic already has user id in it, we should explicitly check that user can subscribe to his own topic using `config.auth.websocketTopicAuth`
+Currently, any user can subscribe to the any topic and receive published messages.
+
+However you can prevent some users from subscribing to some topics and prevent them to get data streamed to the topic. Or vise-versa you can prevent all users and allow only some users to subscribe to the topic.
+
+In our example though topic already has user id in it, we should explicitly check that user can subscribe to his own topic using `config.auth.websocketTopicAuth`
 
 
 ```javascript title="./index.ts"
@@ -203,4 +207,34 @@ const admin = new AdminForth({
   ...
 });
 
-``` 
+``` 
+
+There is still method to bypass this websocketTopicAuth check by using special topic `/opentopic/`. In other words if topic starts with `/opentopic/` it will be allowed to subscribe by any user bypassing `websocketTopicAuth` call at all.
+
+### Publish authorization
+
+Best way to secure the data published to websoket is use websocketTopicAuth method. It will be called once on subscription and if it will not allow access it will completely prevent user from subscribing to the topic.
+
+However you can move auth check to publish call. It has a third parameter of publish function. Imagine you rewrite `websocketTopicAuth` to allow all users to subscribe to any topic:
+
+```typescript title="./index.ts"
+...
+websocketTopicAuth: async (topic: string, adminUser: AdminUser) => {
+  return true;
+},
+...
+```
+
+(Or you are using `/opentopic/`)
+
+Now you can move the check to publish call:
+
+```typescript title="./index.ts"
+
+admin.websocket.publish(topic, { type: 'message', totalCost }, async (adminUser: AdminUser): Promise<boolean> => {
+  return adminUser.dbUser.id === record.realtor_id;
+});
+
+```
+
+In this case during publish call it will check all users who subscribed to the topic and do actual publish to only those who are allowed to receive the message. This method requires more CPU resources and generally is not recommended.

adminforth/documentation/docs/tutorial/05-Plugins/07-email-password-reset.md

@@ -11,8 +11,8 @@ Plugin allows to reset password for admin users who forgot their password by sen
 Installation:
 
 ```bash
-npm install @adminforth/email-password-reset
-npm install @adminforth/email-adapter-aws-ses
+npm install @adminforth/email-password-reset --save
+npm install @adminforth/email-adapter-aws-ses --save
 ```
 
 Import plugin:

adminforth/documentation/docs/tutorial/05-Plugins/08-import-export.md

@@ -13,7 +13,7 @@ This plugin is mostly useful for next use cases:
 To install the plugin:
 
 ```bash
-npm install @adminforth/import-export
+npm install @adminforth/import-export --save
 ```
 
 ## Usage

adminforth/documentation/docs/tutorial/05-Plugins/09-open-signup.md

@@ -8,7 +8,7 @@ This is useful when you want to allow anyone to sign up and assign some low-leve
 To install the plugin:
 
 ```bash
-npm install @adminforth/open-signup
+npm install @adminforth/open-signup --save
 ```
 
 

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

@@ -1,9 +1,9 @@
 # Internationalization (i18n)
 
-This plugin allows you to translate your AdminForth application to multiple languages.
+This plugin allows you translate your AdminForth application to multiple languages.
 Main features:
-- Stores all translation strings in your application in a single resource. Basically you can set allowed actions to Developers/Translators role only if you don't want other users to see the translations.
-- Supports AI completion adapters to help with translations. For example, you can use OpenAI ChatGPT to generate translations.
+- Stores all translation strings in your application in a single AdminForth resource. You can set [allowed actions](/docs/tutorial/Customization/limitingAccess/#disable-some-action-based-on-logged-in-user-record-or-role) only  to Developers/Translators role if you don't want other users to see/edit the translations.
+- Supports AI completion adapters to help with translations. For example, you can use OpenAI ChatGPT to generate translations. Supports correct pluralization, even for Slavic languages.
 - Supports any number of languages.
 
 
@@ -15,7 +15,8 @@ Under the hood it uses vue-i18n library and provides several additional faciliti
 To install the plugin:
 
 ```bash
-npm install @adminforth/i18n
+npm install @adminforth/i18n --save
+npm install @adminforth/completion-adapter-open-ai-chat-gpt --save
 ```
 
 For example lets add translations to next 4 languages: Ukrainian, Japanese, French, Spanish. Also we will support basic translation for English.
@@ -86,6 +87,11 @@ export default {
 
       completeAdapter: new CompletionAdapterOpenAIChatGPT({
         openAiApiKey: process.env.OPENAI_API_KEY as string,
+        model: 'gpt-4o-mini',
+        expert: {
+          // for UI translation it is better to lower down the temperature from default 0.7. Less creative and more accurate
+          temperature: 0.5,
+        },
       }),
     }),
 
@@ -137,6 +143,12 @@ export default {
 } as AdminForthResourceInput;
 ```
 
+Add `OPENAI_API_KEY` to your `.env` file:
+
+```bash
+OPENAI_API_KEY=your_openai_api_key
+```
+
 Also add the resource to main file and add menu item in `./index.ts`:
 
 ```ts title='./index.ts'
@@ -169,7 +181,7 @@ const adminForth = new AdminForth({
 
 ```
 
-This is it, now you should start your app and see the translations resource in the menu. 
+This is it, now you should restart your app and see the translations resource in the menu. 
 
 You can add translations for each language manually or use Bulk actions to generate translations with AI completion adapter.
 
@@ -202,13 +214,13 @@ This is generally helps to understand the context of the translation for AI comp
 For example if you have string "Showing 1 to 10 of 100 entries" you can of course simply do
 
 ```html
-{{$t('Showing')} {{from}} {{$t('to')}} {{to}} {{$t('of')}} {{total}} {{$t('entries')}}
-```
+{{ $t('Showing')}} {{from}} {{$t('to')}} {{to}} {{$t('of')}} {{total}} {{$t('entries') }}
+``` 
 
 And it will form 4 translation strings. But it is much better to have it as single string with variables like this:
 
 ```html
-{{$t('Showing {from} to {to} of {total} entries', { from, to, total })}
+{{ $t('Showing {from} to {to} of {total} entries', { from, to, total } ) }}
 ```
 
 
@@ -254,6 +266,30 @@ const adminForth = new AdminForth({
 
 ```
 
+### HTML in translations
+
+Sometimes you might want to have HTML in translations. You can use `v-html` directive for this. For example:
+
+```html
+<h1 class="mb-4 text-xl font-extrabold text-gray-900 dark:text-white md:text-2xl lg:text-3xl"
+      v-html='$t("<span class=\"text-transparent bg-clip-text bg-gradient-to-r to-emerald-600 from-sky-400\">Apartments</span> Statistics.")'></h1>
+```
+
+> 🪪 Please keep in mind that roles who have access to translations resource can make HTML injections, though anyway if you are using [Audit Log](/docs/tutorial/Plugins/AuditLog/) plugin you can track all changes in translations and understand who made them.
+
+### Pluralization
+
+Frontend uses same pluralization rules as vue-i18n library. You can use it in the same way. For example:
+
+```html
+{{ $t('Apartment last 7 days | Apartments last 7 days', data.totalAparts) }}
+```
+
+For English it will use 2 pluralization forms (1 and other), for Slavic languages, LLM adapter will be instructed to generate 4 forms: for zero, for one, for 2-4 and for 5+:
+
+![alt text](image-4.png)
+
+
 ## Translations in custom APIs
 
 Sometimes you need to return a translated error or success message from your API. You can use special `tr` function for this.
@@ -328,7 +364,7 @@ If you don't use params, you can use `tr` without third param:
 > So to collect all translations you should use your app for some time and make sure all strings are used at
 > In future we plan to add backend strings collection in same way like frontend strings are collected.
 
-# Translating messaged within bulk action
+## Translating messaged within bulk action
 
 Label adn confirm strings of bulk actions are already translated by AdminForth, but 
 `succesMessage` returned by action function should be translated manually because of the dynamic nature of the message.