pluralization support for backend tr function, otimisation for pluralisation LLM instructions

Author: ivictbor

Changelog.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [v1.5.12] - next
 
+### Fixed
+- beforeEnter navigation guard on login route to check user already logged in postponed onMounted and created undefined rest request e.g. on signupPage (with race condition). Now it is called in component
+- AFCL progress bar component
+- sorting for virtual columns is disabled by default now, and sorting icon appers only if user sets column.sortable = true, in this case user has to implement sorting in `list.beforeDatasourceRequest` hook
+
+### Improved
+- add pluralization support exposed `tr` function
+
+
 ## [v1.5.11] - 2025-01-07
 
 Major AFCL update https://adminforth.dev/docs/tutorial/Customization/afcl/

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

@@ -20,7 +20,7 @@ Create a Vue component in the `custom` directory of your project, e.g. `Dashboar
       <div class="max-w-md w-full bg-white rounded-lg shadow dark:bg-gray-800 p-4 md:p-5" v-if="data">
         <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">{{  $t('Apartment last 7 days | 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>
         <BarChart
           :data="apartsCountsByDaysChart"

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

@@ -299,10 +299,13 @@ Frontend uses same pluralization rules as vue-i18n library. You can use it in th
 {{ $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+:
+For English it will use 2 pluralization forms (1 and other), for Slavic languages, LLM adapter will be instructed to generate 4 forms via Pipe: for zero, for one, for 2-4 and for 5+:
 
 ![alt text](image-4.png)
 
+> 🚧 Cheaper LLM models like `gpt-4o-mini` might still purely generate pluralisation slavic forms, even despite the fact plugin carefully
+instructs the model and gives it examples. So if you are using cheap model we recommend reviewing generated translations for plurals and fixing them manually. You can use filter with '|' parameter to filter out strings with pluralisation.
+
 
 ## Limiting access to translating
 
@@ -385,6 +388,25 @@ 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.
 
+### Pluralisation in backend translations
+
+In same way you can use pluralisation in backend translations:
+
+```ts title="./index.ts"
+await req.tr('{count} apartment last 7 days | {count} apartments last 7 days', 'customApis', { count: totalAparts }, totalAparts) 
+```
+
+Please pay attention that you should pass `totalAparts` as last argument to `tr` function. 
+
+If you don't have parameters, you can pass empty object as 3rd argument:
+
+```ts title="./index.ts"
+await req.tr('Apartment last 7 days | Apartments last 7 days', 'customApis', {}, totalAparts) 
+```
+
+Pluralisation rules are the same as in frontend
+
+
 ## Translating messages within bulk action
 
 Label and confirm strings of bulk actions are already translated by AdminForth, but 

adminforth/package-lock.json

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

adminforth/package.json

@@ -5,6 +5,15 @@ 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).
 
+## [1.0.23] - next
+
+### Improved
+
+- Better instructions for LLM pluralization Slavik messages
+
+### Added
+- support for pluralization in Backend `tr` function
+
 ## [1.0.22]
 
 ### Fixed

adminforth/plugins/i18n/Changelog.md

@@ -429,7 +429,7 @@ export default class I18nPlugin extends AdminForthPlugin {
 
     const prompt = `
 I need to translate strings in JSON to ${lang} (${langName}) language from English for my web app.
-${requestSlavicPlurals ? `You should provide 4 translations (in format zero | singular | 2-4 | 5+) e.g. ${SLAVIC_PLURAL_EXAMPLES[lang]}` : ''}
+${requestSlavicPlurals ? `You should provide 4 slavic forms (in format "zero count | singular count | 2-4 | 5+") e.g. "apple | apples" should become "${SLAVIC_PLURAL_EXAMPLES[lang]}"` : ''}
 Keep keys, as is, write translation into values! Here are the strings:
 
 \`\`\`json
@@ -449,6 +449,7 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
       300,
     );
 
+
     if (resp.error) {
       throw new AiTranslateError(resp.error);
     }
@@ -568,8 +569,11 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
     await Promise.all(
       Object.entries(updateStrings).map(
         async ([_, { updates, strId }]: [string, { updates: any, category: string, strId: string }]) => {
+          // get old full record
+          const oldRecord = await this.adminforth.resource(this.resourceConfig.resourceId).get([Filters.EQ(this.primaryKeyFieldName, strId)]);
+
           // because this will translate all languages, we can set completedLangs to all languages
-          const futureCompletedFieldValue = await this.computeCompletedFieldValue(updates); 
+          const futureCompletedFieldValue = await this.computeCompletedFieldValue({ ...oldRecord, ...updates });
 
           await this.adminforth.resource(this.resourceConfig.resourceId).update(strId, {
             ...updates,
@@ -675,7 +679,7 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
     // in this plugin we will use plugin to fill the database with missing language messages
     this.tryProcessAndWatch(adminforth);
 
-    adminforth.tr = async (msg: string | null | undefined, category: string, lang: string, params): Promise<string> => {
+    adminforth.tr = async (msg: string | null | undefined, category: string, lang: string, params, pluralizationNumber: number): Promise<string> => {
       if (!msg) {
         return msg;
       }
@@ -726,6 +730,11 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
         // cache so even if key does not exist, we will not hit database
         await this.cache.set(cacheKey, result);
       }
+      // if msg has '|' in it, then we need to aplly pluralization
+      if (msg.includes('|')) {
+        result = this.applyPluralization(result, pluralizationNumber, lang);
+      }
+
       if (params) {
         for (const [key, value] of Object.entries(params)) {
           result = result.replace(`{${key}}`, value);
@@ -735,6 +744,36 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
     }
   }
 
+  applyPluralization(str: string, number: number, lang: string): string {
+    const choices = str.split('|');
+    const choicesLength = choices.length;
+
+    if (choicesLength > 2) {
+      // this is slavic pluralization
+      return choices[this.slavicPluralRule(number, choicesLength)];
+    } else {
+      return number === 1 ? choices[0] : choices[1];
+    }
+  }
+  
+    // taken from here https://vue-i18n.intlify.dev/guide/essentials/pluralization.html#custom-pluralization
+  slavicPluralRule(choice, choicesLength) {
+    if (choice === 0) {
+      return 0
+    }
+
+    const teen = choice > 10 && choice < 20
+    const endsWithOne = choice % 10 === 1
+
+    if (!teen && endsWithOne) {
+      return 1
+    }
+    if (!teen && choice % 10 >= 2 && choice % 10 <= 4) {
+      return 2
+    }
+
+    return choicesLength < 4 ? 2 : 3
+  }
   instanceUniqueRepresentation(pluginOptions: any) : string {
     // optional method to return unique string representation of plugin instance. 
     // Needed if plugin can have multiple instances on one resource 

adminforth/plugins/i18n/index.ts

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

adminforth/plugins/i18n/package-lock.json

@@ -255,7 +255,7 @@ class ExpressServer implements IExpressHttpServer {
   translatable(handler) {
     // same as authorize, but injects tr function into request
     return async (req, res, next) => {
-      const tr = (msg: string, category: string, params: any): Promise<string> => this.adminforth.tr(msg, category, req.headers['accept-language'], params);
+      const tr = (msg: string, category: string, params: any, pluralizationNumber?: number): Promise<string> => this.adminforth.tr(msg, category, req.headers['accept-language'], params, pluralizationNumber);
       req.tr = tr;
       handler(req, res, next);
     }
@@ -308,7 +308,7 @@ class ExpressServer implements IExpressHttpServer {
       const requestUrl = req.url;
 
       const acceptLang = headers['accept-language'];
-      const tr = (msg: string, category: string, params: any): Promise<string> => this.adminforth.tr(msg, category, acceptLang, params);
+      const tr = (msg: string, category: string, params: any, pluralizationNumber?: number): Promise<string> => this.adminforth.tr(msg, category, acceptLang, params, pluralizationNumber);
       const input = { body, query, headers, cookies, adminUser, response, requestUrl, _raw_express_req: req, _raw_express_res: res, tr};
 
       let output;