docs improvements

Author: ivictbor

adminforth/documentation/docs/tutorial/05-Plugins/01-AuditLog.md

@@ -54,54 +54,59 @@ Also, it excludes itself to avoid infinte logging loop.
 Add this code in `auditLogs.ts`:
 
 ```ts title='./resources/auditLogs.ts'
-  export default {
-    dataSource: 'maindb', 
-    table: 'audit_logs',
-    columns: [
-      { name: 'id', primaryKey: true, required: false, fillOnCreate: ({initialRecord}: any) => uuid(),
-        showIn: {
-          list: false,
-          edit: false,
-          create: false,
-          filter: false,
-        } },
-      { name: 'created_at', required: false },
-      { name: 'resource_id', required: false },
-      { name: 'user_id', required: false, 
-          foreignResource: {
-          resourceId: 'adminuser',
-        } },
-      { name: 'action', required: false },
-      { name: 'diff', required: false, type: AdminForthDataTypes.JSON, showIn: {
-          list: false,
-          edit: false,
-          create: false,
-          filter: false,
-        } },
-      { name: 'record_id', required: false },
-    ],
-    options: {
-      allowedActions: {
+
+import AuditLogPlugin from "@adminforth/audit-log/index.js";
+import { AdminForthDataTypes } from "adminforth";
+import { randomUUID } from "crypto";
+
+export default {
+  dataSource: 'maindb', 
+  table: 'audit_logs',
+  columns: [
+    { name: 'id', primaryKey: true, required: false, fillOnCreate: ({initialRecord}: any) => randomUUID(),
+      showIn: {
+        list: false,
+        edit: false,
+        create: false,
+        filter: false,
+      } },
+    { name: 'created_at', required: false },
+    { name: 'resource_id', required: false },
+    { name: 'user_id', required: false, 
+        foreignResource: {
+        resourceId: 'adminuser',
+      } },
+    { name: 'action', required: false },
+    { name: 'diff', required: false, type: AdminForthDataTypes.JSON, showIn: {
+        list: false,
         edit: false,
-        delete: false,
-        create: false
+        create: false,
+        filter: false,
+      } },
+    { name: 'record_id', required: false },
+  ],
+  options: {
+    allowedActions: {
+      edit: false,
+      delete: false,
+      create: false
+    }
+  },
+  plugins: [
+    new AuditLogPlugin({
+      // if you want to exclude some resources from logging
+      //excludeResourceIds: ['adminuser'],
+      resourceColumns: {
+        resourceIdColumnName: 'resource_id',
+        resourceActionColumnName: 'action',
+        resourceDataColumnName: 'diff',
+        resourceUserIdColumnName: 'user_id',
+        resourceRecordIdColumnName: 'record_id',
+        resourceCreatedColumnName: 'created_at'
       }
-    },
-    plugins: [
-      new AuditLogPlugin({
-        // if you want to exclude some resources from logging
-        //excludeResourceIds: ['adminuser'],
-        resourceColumns: {
-          resourceIdColumnName: 'resource_id',
-          resourceActionColumnName: 'action',
-          resourceDataColumnName: 'diff',
-          resourceUserIdColumnName: 'user_id',
-          resourceRecordIdColumnName: 'record_id',
-          resourceCreatedColumnName: 'created_at'
-        }
-      }),
-    ],
-  }
+    }),
+  ],
+}
 ```
 
 Then you need to import `./resources/auditLogs`:

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

@@ -40,6 +40,7 @@ model translations {
     // we need both indexes on en_string+category and separately on category
     @@index([en_string, category])
     @@index([category])
+    @@index([completedLangs])
 }
 ```
 
@@ -454,7 +455,7 @@ import { admin } from '../index';
 
 You can use this module not only to translate admin area of your application but also to translate other parts like SEO-facing or user-facing services.
 This will allow you to reuse the same functionality and AI completion adapters for all your translations and manage them in one place. 
-For example in this app we will consider translating a Nuxt.js SEO-centric frontend which we want to translate with [vue-i18n](https://vue-i18n.intlify.dev/).
+For example in this app we will consider translating a Nuxt.js SEO-centric frontend which we want to translate with [nuxt i18n](https://i18n.nuxtjs.org/).
 
 To do it you need to use 2 exposed methods from the plugin: `feedCategoryTranslations` and `getCategoryTranslations`. 
 
@@ -478,7 +479,7 @@ First of all, at some step, e.g. CI pipeline you should get all translation stri
 
       admin.getPluginByClassName<I18nPlugin>('I18nPlugin').feedCategoryTranslations(
         messagesForFeed,
-        'nextApp'
+        'seoApp'
       )
 
       res.json({
@@ -489,60 +490,99 @@ First of all, at some step, e.g. CI pipeline you should get all translation stri
 
 ```
 
-For extracting 18n messages we use [vue-i18n-extract](https://github.com/Spittal/vue-i18n-extract) package. 
+For extracting i18n 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"
+    "i18n:extract": "echo '{}' > i18n-empty.json && vue-i18n-extract report --vueFiles './?(pages|components)/**/*.?(js|vue)' --output ./i18n-messages.json --languageFiles 'i18n-empty.json' --add",
+    "i18n:feed-to-local-backoffice": "npm run i18n:extract && curl -X POST -H 'Content-Type: application/json' -d @i18n-messages.json http://localhost:3000/feed-nuxt-strings"
   }
 }
 ```
 
-Make sure to replace `adminforth:3000` with AdminForth API URL. We are assuming it is docker container name in internal docker network.
+> For plain non-nuxt apps `--vueFiles './?(pages|components)/**/*.?(js|vue)'` should be replaced with `--vueFiles './src/**/*.?(js|vue)'`
 
-So in the pipeline you should run `npm run i18n:feed-to-backoffice` to extract messages from your Nuxt.js app and feed them to AdminForth.
+Make sure to replace `localhost:3000` with AdminForth API URL.
 
-> 👆 The example method is just a stub, please make sure you not expose endpoint 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.
+So locally you can run `npm run i18n:feed-to-local-backoffice` to extract messages from your Nuxt.js app and feed them to AdminForth.
 
 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-nuxt-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}`,
+const { locale, setLocaleMessage, } = useI18n();
+const { data: messages } = await useFetch(
+  useRuntimeConfig().public.adminUrl + `api/translations/?lang=${locale.value}`,
+  {
     method: 'GET',
-  });
-
-  // set locale and locale message
-  i18n.global.setLocaleMessage(locale, messages.default)
-
-  return nextTick()
+  }
+);
+if (messages.value) {
+  setLocaleMessage(locale.value, messages.value);
+} else {
+  console.error('Translations or language data are missing.');
 }
 ```
 
-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);
+    const lang = req.query.lang as string;
+    const messages = await admin.getPluginByClassName<I18nPlugin>('I18nPlugin').getCategoryTranslations('seoApp', lang);
     res.json(messages);
   }
 );
 ```
 
+Also in `nuxt.config.ts` you can set `prefix_except_default` strategy and put it in `i18n` config as this:
+
+```
+  ...
+  i18n: {
+    locales: ['en', 'uk', 'ja', 'fr'],
+    defaultLocale: 'en',
+    strategy: 'prefix_except_default',
+    detectBrowserLanguage: false,
+  },
+  ...
+```
+
+
+#### Feeding messages during build time
+
+For Dockerized pipelines you can feed messages when building the image in Docker build time:
+
+```dockerfile
+FROM node:22-alpine
+WORKDIR /app
+ADD package.json /app
+ADD package-lock.json /app
+RUN true | npm ci
+ADD . /app
+RUN --mount=type=cache,target=/app/node_modules/.cache true | npm run build
+
+//diff-add
+# Run i18n extraction and API call
+//diff-add
+RUN npm run i18n:extract && \
+//diff-add
+    curl -X POST -H 'Content-Type: application/json' -d @i18n-messages.json http://adminforth:3000/bo/api/feed-nuxt-strings
+
+CMD ["node", ".output/server/index.mjs"]
+EXPOSE 3000
+```
+
+This assumes that `http://adminforth:3000/` is the name of the Docker service running AdminForth. 
+
+This will work if you are building the image in the same Docker network as AdminForth. Otherwise you might need use absolute URL of the AdminForth instance.
+
+> 👆 The example method is just a stub, please make sure you not expose endpoint to public or add some simple authorization on it,
+> otherwise someone might flood you with dump translations requests.
+
+
 ### Get language names
 
 Also you can use handy method to get language names in native and English form with emoji flags:
@@ -575,3 +615,16 @@ Response will look like this:
             "emojiFlag": "🇦🇷"
         },
 ```
+
+### Disable translation for admin (external app only)
+
+If you want to use this plugin only for external app, and not backoffice, which is probably the case, you can disable translation for admin by setting `externalAppOnly` to `true`:
+
+```ts title="./resources/translations.ts"
+    new I18nPlugin({
+    //diff-add
+      externalAppOnly: true,
+      supportedLanguages: ['en', 'uk', 'ja', 'fr'],
+      ...
+    }),
+```

live-demo/app/resources/translations.ts

@@ -32,9 +32,7 @@ export default {
   },
   plugins: [
     new I18nPlugin({
-      supportedLanguages: ['en', 'uk', 'ja', 'fr', 'de'],
-
-      // names of the fields in the resource which will store translations
+      supportedLanguages: ['en', 'uk', 'ja', 'fr', 'de'],      // names of the fields in the resource which will store translations
       translationFieldNames: {
         en: 'en_string',
         uk: 'uk_string',