docs: enhance i18n plugin documentation with BCP47 language code support and primary language configuration details

Author: SerVitasik

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

@@ -5,6 +5,8 @@ Main features:
 - Stores all translation strings in your application in a single AdminForth resource. You can set [allowed actions](/docs/tutorial/Customization/limitingAccess/) 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.
+- Supports BCP47 language codes (e.g., `en-GB`, `pt-BR`) for regional language variants.
+- Configurable primary language.
 
 
 Under the hood it uses vue-i18n library and provides several additional facilities to make the translation process easier.
@@ -46,6 +48,8 @@ model translations {
 
 If you want more languages, just add more fields like `uk_string`, `ja_string`, `fr_string`, `es_string` to the model.
 
+> 💡 **Tip**: For regional language variants, you can also use BCP47 codes like `en-GB`, `pt-BR`, `fr-CA` and add corresponding fields like `enGB_string`, `ptBR_string`, `frCA_string`. See the [BCP47 Language Code Support](#bcp47-language-code-support) section for more details.
+
 Next, add resource for translations:
 
 ```ts title='./resources/translations.ts'
@@ -86,6 +90,9 @@ export default {
       // will hel to filter out incomplete translations
       completedFieldName: 'completedLangs',
 
+      // optional: set primary language (defaults to 'en' if not specified)
+      // primaryLanguage: 'fr', // Uncomment to set French as primary language
+
       completeAdapter: new CompletionAdapterOpenAIChatGPT({
         openAiApiKey: process.env.OPENAI_API_KEY as string,
         model: 'gpt-4o-mini',
@@ -205,6 +212,125 @@ You can add translations for each language manually or use Bulk actions to gener
 
 For simplicity you can also use filter to get only untranslated strings and complete them one by one (filter name "Fully translated" in the filter).
 
+## BCP47 Language Code Support
+
+The i18n plugin supports BCP47 language tags, which allow you to specify regional variants of languages. This is particularly useful for applications that need to support different regional dialects or cultural variations.
+
+### Supported Language Code Formats
+
+- **ISO 639-1 codes**: Basic language codes like `en`, `fr`, `de`, `es`
+- **BCP47 tags**: Regional variants like `en-GB` (British English), `pt-BR` (Brazilian Portuguese), `en-US` (American English)
+
+### Example with Regional Variants
+
+Here's how to configure the plugin to support both basic and regional language codes:
+
+```ts title='./resources/translations.ts'
+export default {
+  dataSource: "maindb",
+  table: "translations",
+  resourceId: "translations",
+  label: "Translations",
+
+  recordLabel: (r: any) => `✍️ ${r.en_string}`,
+  plugins: [
+    new I18nPlugin({
+      // Support both basic and regional language codes
+      supportedLanguages: ['en', 'en-GB', 'en-US', 'pt', 'pt-BR', 'fr', 'fr-CA'],
+
+      // Map language codes to database field names
+      translationFieldNames: {
+        en: 'en_string',
+        'en-GB': 'enGB_string',
+        'en-US': 'enUS_string',
+        pt: 'pt_string',
+        'pt-BR': 'ptBR_string',
+        fr: 'fr_string',
+        'fr-CA': 'frCA_string',
+      },
+
+      categoryFieldName: 'category',
+      sourceFieldName: 'source',
+      completedFieldName: 'completedLangs',
+
+      completeAdapter: new CompletionAdapterOpenAIChatGPT({
+        openAiApiKey: process.env.OPENAI_API_KEY as string,
+        model: 'gpt-4o-mini',
+        expert: {
+          temperature: 0.5,
+        },
+      }),
+    }),
+  ],
+  // ... rest of configuration
+} as AdminForthResourceInput;
+```
+
+### Database Schema for Regional Variants
+
+When using BCP47 codes, make sure your database schema includes fields for each regional variant:
+
+```ts title='./schema.prisma'
+model translations {
+    id              String   @id
+    en_string        String
+    created_at       DateTime
+    
+    // Basic language codes
+    fr_string        String?
+    pt_string        String?
+    
+    // Regional variants (BCP47)
+    enGB_string      String?  // British English
+    enUS_string      String?  // American English
+    ptBR_string      String?  // Brazilian Portuguese
+    frCA_string      String?  // Canadian French
+    
+    category         String
+    source           String?
+    completedLangs   String?
+    
+    @@index([en_string, category])
+    @@index([category])
+    @@index([completedLangs])
+}
+```
+
+## Primary Language Configuration
+
+The `primaryLanguage` option allows you to set the default language for your application. This is particularly useful when your application's primary language is not English.
+
+### How Primary Language Works
+
+- **Default Language**: The language shown to users by default
+- **Fallback Chain**: When a translation is missing, the system falls back to: `requested language` → `primaryLanguage` → `English`
+- **Translation Source**: English (`en_string`) is always used as the source for AI translations, regardless of the primary language setting
+
+### Example: Portuguese as Primary Language
+
+```ts title='./resources/translations.ts'
+export default {
+  // ... other configuration
+  plugins: [
+    new I18nPlugin({
+      // Set Portuguese as the primary language
+      primaryLanguage: 'pt-BR',
+      
+      supportedLanguages: ['pt-BR', 'en', 'en-GB', 'es', 'fr'],
+      translationFieldNames: {
+        'pt-BR': 'ptBR_string',
+        en: 'en_string',
+        'en-GB': 'enGB_string',
+        es: 'es_string',
+        fr: 'fr_string',
+      },
+      
+      // ... rest of configuration
+    }),
+  ],
+  // ... rest of configuration
+} as AdminForthResourceInput;
+```
 
 ## Translation for custom components
 
@@ -458,6 +584,8 @@ If you don't use params, you can use `tr` without third param:
 }
 ```
 
+> 🔄 **Fallback Behavior**: The `tr` function automatically handles fallbacks when translations are missing. It follows this chain: `requested language` → `primaryLanguage` → `English`. This ensures users always see content in a language they can understand, even if specific translations are missing.
+
 > 🙅‍♂️ Temporary limitation: For now all translations strings for backend (adminforth internal and for from custom APIs)
  appear in Translations resource and table only after they are used. So greeting string will appear in the Translations table only after the first request to the API which reaches the `tr` function call. 
 > So to collect all translations you should use your app for some time and make sure all strings are used at