@adminforth/i18n 1.3.7 → 1.4.1

package/build.log

@@ -17,5 +17,5 @@ custom/package-lock.json
 custom/package.json
 custom/tsconfig.json
 
-sent 32,187 bytes  received 248 bytes  64,870.00 bytes/sec
-total size is 31,254  speedup is 0.96
+sent 32,964 bytes  received 248 bytes  66,424.00 bytes/sec
+total size is 32,031  speedup is 0.96

package/custom/LanguageEveryPageLoader.vue

@@ -3,13 +3,15 @@
 <script setup>
 import { onMounted } from 'vue';
 import { useI18n } from 'vue-i18n';
-import { setLang, getLocalLang } from './langCommon';
+import { setLang, getLocalLang, setLocalLang } from './langCommon';
 
 const { setLocaleMessage, locale } = useI18n();
 
 const props = defineProps(['meta']);
 
 onMounted(() => {
-  setLang({ setLocaleMessage, locale }, props.meta.pluginInstanceId, getLocalLang(props.meta.supportedLanguages));
+  const langIso = getLocalLang(props.meta.supportedLanguages, props.meta.primaryLanguage);
+  setLocalLang(langIso);
+  setLang({ setLocaleMessage, locale }, props.meta.pluginInstanceId, langIso);
 });
 </script>

package/custom/LanguageInUserMenu.vue

@@ -1,18 +1,19 @@
 <template>
   <div class="min-w-40">
-    <div class="cursor-pointer flex items-center gap-1 block px-4 py-2 text-sm text-black 
+    <div class="cursor-pointer flex items-center justify-between gap-1 block px-4 py-2 text-sm text-black 
       hover:bg-html dark:text-darkSidebarTextHover dark:hover:bg-darkSidebarItemHover dark:hover:text-darkSidebarTextActive 
       w-full select-none	"
       :class="{ 'bg-black bg-opacity-10	': showDropdown }"
       @click="showDropdown = !showDropdown"
     >
-      <span class="mr-1">
-        <span class="flag-icon"
-          :class="`flag-icon-${getCountryCodeFromLangCode(selectedOption.value)}`"
-        ></span>
-      </span>
-      <span>{{ selectedOption.label }}</span>
-
+      <div>
+        <span class="mr-1">
+          <span class="flag-icon"
+            :class="`flag-icon-${getCountryCodeFromLangCode(selectedOption.value)}`"
+          ></span>
+        </span>
+        <span>{{ selectedOption.label }}</span>
+      </div>
       <IconCaretDownSolid class="h-5 w-5 text-lightPrimary dark:text-gray-400 opacity-50 transition duration-150 ease-in"
           :class="{ 'transform rotate-180': showDropdown }"
       />
@@ -70,9 +71,10 @@ function doChangeLang(lang) {
 
 const options = computed(() => {
   return props.meta.supportedLanguages.map((lang) => {
+    const region = String(lang.code).split('-')[1]?.toUpperCase();
     return {
       value: lang.code,
-      label: lang.name,
+      label: region ? `${lang.name} (${region})` : lang.name,
     };
   });
 });
@@ -87,6 +89,6 @@ const selectedOption = computed(() => {
 
 
 onMounted(() => {
-  selectedLanguage.value = getLocalLang(props.meta.supportedLanguages);
+  selectedLanguage.value = getLocalLang(props.meta.supportedLanguages, props.meta.primaryLanguage);
 });
 </script>

package/custom/LanguageUnderLogin.vue

@@ -53,14 +53,15 @@ watch(() => selectedLanguage.value, async (newVal) => {
 
 const options = computed(() => {
   return props.meta.supportedLanguages.map((lang) => {
+    const region = String(lang.code).split('-')[1]?.toUpperCase();
     return {
       value: lang.code,
-      label: lang.name,
+      label: region ? `${lang.name} (${region})` : lang.name,
     };
   });
 });
 
 onMounted(() => {
-  selectedLanguage.value = getLocalLang(props.meta.supportedLanguages);
+  selectedLanguage.value = getLocalLang(props.meta.supportedLanguages, props.meta.primaryLanguage);
 });
 </script>

package/custom/langCommon.ts

@@ -4,6 +4,7 @@ import dayjsLocales from './dayjsLocales';
 import datepickerLocales from './datepickerLocales';
 import dayjs from 'dayjs';
 import Datepicker from "flowbite-datepicker/Datepicker";
+import type { SupportedLanguage } from '../types';
 
 
 const messagesCache: Record<
@@ -78,13 +79,17 @@ const countryISO31661ByLangISO6391 = {
 };
 
 export function getCountryCodeFromLangCode(langCode) {
-    return countryISO31661ByLangISO6391[langCode] || langCode;
+    const [primary, region] = String(langCode).split('-');
+    if (region && /^[A-Za-z]{2}$/.test(region)) {
+        return region.toLowerCase();
+    }
+    return countryISO31661ByLangISO6391[primary] || primary;
 }
 
 
 const LS_LANG_KEY = `afLanguage`;
 
-export function getLocalLang(supportedLanguages: {code}[]): string {
+export function getLocalLang(supportedLanguages: {code}[], primaryLanguage?: SupportedLanguage): string {
     let lsLang = localStorage.getItem(LS_LANG_KEY);
     // if someone screwed up the local storage or we stopped language support, lets check if it is in supported languages
     if (lsLang && !supportedLanguages.find((l) => l.code == lsLang)) {
@@ -99,6 +104,10 @@ export function getLocalLang(supportedLanguages: {code}[]): string {
     if (foundLang) {
         return foundLang.code;
     }
+    if (primaryLanguage && supportedLanguages.find((l) => l.code == primaryLanguage)) {
+        return primaryLanguage;
+    }
+
     return supportedLanguages[0].code;
 }
 

package/dist/custom/LanguageEveryPageLoader.vue

@@ -3,13 +3,15 @@
 <script setup>
 import { onMounted } from 'vue';
 import { useI18n } from 'vue-i18n';
-import { setLang, getLocalLang } from './langCommon';
+import { setLang, getLocalLang, setLocalLang } from './langCommon';
 
 const { setLocaleMessage, locale } = useI18n();
 
 const props = defineProps(['meta']);
 
 onMounted(() => {
-  setLang({ setLocaleMessage, locale }, props.meta.pluginInstanceId, getLocalLang(props.meta.supportedLanguages));
+  const langIso = getLocalLang(props.meta.supportedLanguages, props.meta.primaryLanguage);
+  setLocalLang(langIso);
+  setLang({ setLocaleMessage, locale }, props.meta.pluginInstanceId, langIso);
 });
 </script>

package/dist/custom/LanguageInUserMenu.vue

@@ -1,18 +1,19 @@
 <template>
   <div class="min-w-40">
-    <div class="cursor-pointer flex items-center gap-1 block px-4 py-2 text-sm text-black 
+    <div class="cursor-pointer flex items-center justify-between gap-1 block px-4 py-2 text-sm text-black 
       hover:bg-html dark:text-darkSidebarTextHover dark:hover:bg-darkSidebarItemHover dark:hover:text-darkSidebarTextActive 
       w-full select-none	"
       :class="{ 'bg-black bg-opacity-10	': showDropdown }"
       @click="showDropdown = !showDropdown"
     >
-      <span class="mr-1">
-        <span class="flag-icon"
-          :class="`flag-icon-${getCountryCodeFromLangCode(selectedOption.value)}`"
-        ></span>
-      </span>
-      <span>{{ selectedOption.label }}</span>
-
+      <div>
+        <span class="mr-1">
+          <span class="flag-icon"
+            :class="`flag-icon-${getCountryCodeFromLangCode(selectedOption.value)}`"
+          ></span>
+        </span>
+        <span>{{ selectedOption.label }}</span>
+      </div>
       <IconCaretDownSolid class="h-5 w-5 text-lightPrimary dark:text-gray-400 opacity-50 transition duration-150 ease-in"
           :class="{ 'transform rotate-180': showDropdown }"
       />
@@ -70,9 +71,10 @@ function doChangeLang(lang) {
 
 const options = computed(() => {
   return props.meta.supportedLanguages.map((lang) => {
+    const region = String(lang.code).split('-')[1]?.toUpperCase();
     return {
       value: lang.code,
-      label: lang.name,
+      label: region ? `${lang.name} (${region})` : lang.name,
     };
   });
 });
@@ -87,6 +89,6 @@ const selectedOption = computed(() => {
 
 
 onMounted(() => {
-  selectedLanguage.value = getLocalLang(props.meta.supportedLanguages);
+  selectedLanguage.value = getLocalLang(props.meta.supportedLanguages, props.meta.primaryLanguage);
 });
 </script>

package/dist/custom/LanguageUnderLogin.vue

@@ -53,14 +53,15 @@ watch(() => selectedLanguage.value, async (newVal) => {
 
 const options = computed(() => {
   return props.meta.supportedLanguages.map((lang) => {
+    const region = String(lang.code).split('-')[1]?.toUpperCase();
     return {
       value: lang.code,
-      label: lang.name,
+      label: region ? `${lang.name} (${region})` : lang.name,
     };
   });
 });
 
 onMounted(() => {
-  selectedLanguage.value = getLocalLang(props.meta.supportedLanguages);
+  selectedLanguage.value = getLocalLang(props.meta.supportedLanguages, props.meta.primaryLanguage);
 });
 </script>

package/dist/custom/langCommon.ts

@@ -4,6 +4,7 @@ import dayjsLocales from './dayjsLocales';
 import datepickerLocales from './datepickerLocales';
 import dayjs from 'dayjs';
 import Datepicker from "flowbite-datepicker/Datepicker";
+import type { SupportedLanguage } from '../types';
 
 
 const messagesCache: Record<
@@ -78,13 +79,17 @@ const countryISO31661ByLangISO6391 = {
 };
 
 export function getCountryCodeFromLangCode(langCode) {
-    return countryISO31661ByLangISO6391[langCode] || langCode;
+    const [primary, region] = String(langCode).split('-');
+    if (region && /^[A-Za-z]{2}$/.test(region)) {
+        return region.toLowerCase();
+    }
+    return countryISO31661ByLangISO6391[primary] || primary;
 }
 
 
 const LS_LANG_KEY = `afLanguage`;
 
-export function getLocalLang(supportedLanguages: {code}[]): string {
+export function getLocalLang(supportedLanguages: {code}[], primaryLanguage?: SupportedLanguage): string {
     let lsLang = localStorage.getItem(LS_LANG_KEY);
     // if someone screwed up the local storage or we stopped language support, lets check if it is in supported languages
     if (lsLang && !supportedLanguages.find((l) => l.code == lsLang)) {
@@ -99,6 +104,10 @@ export function getLocalLang(supportedLanguages: {code}[]): string {
     if (foundLang) {
         return foundLang.code;
     }
+    if (primaryLanguage && supportedLanguages.find((l) => l.code == primaryLanguage)) {
+        return primaryLanguage;
+    }
+
     return supportedLanguages[0].code;
 }
 

package/dist/index.js

@@ -9,6 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { AdminForthPlugin, Filters, suggestIfTypo, AdminForthDataTypes, RAMLock } from "adminforth";
 import iso6391 from 'iso-639-1';
+import { iso31661Alpha2ToAlpha3 } from 'iso-3166';
 import path from 'path';
 import fs from 'fs-extra';
 import chokidar from 'chokidar';
@@ -37,9 +38,27 @@ const countryISO31661ByLangISO6391 = {
     uk: 'ua', // Ukrainian → Ukraine
     ur: 'pk', // Urdu → Pakistan
 };
-function getCountryCodeFromLangCode(langCode) {
+function getCountryCodeFromLangCode(lang) {
+    const [langCode, region] = String(lang).split('-');
+    if (region && /^[A-Z]{2}$/.test(region)) {
+        return region.toLowerCase();
+    }
     return countryISO31661ByLangISO6391[langCode] || langCode;
 }
+function getPrimaryLanguageCode(langCode) {
+    return String(langCode).split('-')[0];
+}
+function isValidSupportedLanguageTag(langCode) {
+    const [primary, region] = String(langCode).split('-');
+    if (!iso6391.validate(primary)) {
+        return false;
+    }
+    if (!region) {
+        return true;
+    }
+    const regionUpper = region.toUpperCase();
+    return /^[A-Z]{2}$/.test(regionUpper) && (regionUpper in iso31661Alpha2ToAlpha3);
+}
 class CachingAdapterMemory {
     constructor() {
         this.cache = {};
@@ -84,6 +103,7 @@ export default class I18nPlugin extends AdminForthPlugin {
         this.options = options;
         this.cache = new CachingAdapterMemory();
         this.trFieldNames = {};
+        this.primaryLanguage = options.primaryLanguage || 'en';
     }
     computeCompletedFieldValue(record) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -119,10 +139,10 @@ export default class I18nPlugin extends AdminForthPlugin {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
             _super.modifyResourceConfig.call(this, adminforth, resourceConfig);
-            // check each supported language is valid ISO 639-1 code
+            // validate each supported language: ISO 639-1 or BCP-47 with region (e.g., en-GB)
             this.options.supportedLanguages.forEach((lang) => {
-                if (!iso6391.validate(lang)) {
-                    throw new Error(`Invalid language code ${lang}, please define valid ISO 639-1 language code (2 lowercase letters)`);
+                if (!isValidSupportedLanguageTag(lang)) {
+                    throw new Error(`Invalid language code ${lang}. Use ISO 639-1 (e.g., 'en') or BCP-47 with region (e.g., 'en-GB').`);
                 }
             });
             this.externalAppOnly = this.options.externalAppOnly === true;
@@ -239,10 +259,11 @@ export default class I18nPlugin extends AdminForthPlugin {
             const compMeta = {
                 brandSlug: adminforth.config.customization.brandNameSlug,
                 pluginInstanceId: this.pluginInstanceId,
+                primaryLanguage: this.primaryLanguage,
                 supportedLanguages: this.options.supportedLanguages.map(lang => ({
                     code: lang,
                     // lang name on on language native name
-                    name: iso6391.getNativeName(lang),
+                    name: iso6391.getNativeName(getPrimaryLanguageCode(lang)),
                 }))
             };
             // add underLogin component
@@ -424,6 +445,7 @@ export default class I18nPlugin extends AdminForthPlugin {
     }
     translateToLang(langIsoCode_1, strings_1) {
         return __awaiter(this, arguments, void 0, function* (langIsoCode, strings, plurals = false, translations, updateStrings = {}) {
+            var _a;
             const maxKeysInOneReq = 10;
             if (strings.length === 0) {
                 return [];
@@ -439,21 +461,23 @@ export default class I18nPlugin extends AdminForthPlugin {
                 return totalTranslated;
             }
             const lang = langIsoCode;
-            const langName = iso6391.getName(lang);
-            const requestSlavicPlurals = Object.keys(SLAVIC_PLURAL_EXAMPLES).includes(lang) && plurals;
+            const primaryLang = getPrimaryLanguageCode(lang);
+            const langName = iso6391.getName(primaryLang);
+            const requestSlavicPlurals = Object.keys(SLAVIC_PLURAL_EXAMPLES).includes(primaryLang) && plurals;
+            const region = ((_a = String(lang).split('-')[1]) === null || _a === void 0 ? void 0 : _a.toUpperCase()) || '';
             const prompt = `
-I need to translate strings in JSON to ${langName} language (ISO 639-1 code ${lang}) from English for my web app.
-${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! If keys have variables (in curly brackets), then translated strings should have them as well (variables itself should not be translated). Here are the strings:
+        I need to translate strings in JSON to ${langName} language (ISO 639-1 code ${lang}) from English for my web app.
+        ${region ? `Use the regional conventions for ${lang} (region ${region}), including spelling, punctuation, and formatting.` : ''}
+        ${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! If keys have variables (in curly brackets), then translated strings should have them as well (variables itself should not be translated). Here are the strings:
 
-\`\`\`json
-${JSON.stringify(strings.reduce((acc, s) => {
+        \`\`\`json
+        ${JSON.stringify(strings.reduce((acc, s) => {
                 acc[s.en_string] = '';
                 return acc;
             }, {}), null, 2)}
-\`\`\`
-`;
-            process.env.HEAVY_DEBUG && console.log(`🪲🔪LLM prompt >> ${prompt.length}, <<${prompt} :\n\n`, JSON.stringify(prompt));
+    \`\`\`
+    `;
             // call OpenAI
             const resp = yield this.options.completeAdapter.complete(prompt, [], prompt.length * 2);
             process.env.HEAVY_DEBUG && console.log(`🪲🔪LLM resp >> ${prompt.length}, <<${resp.content.length} :\n\n`, JSON.stringify(resp));
@@ -657,11 +681,12 @@ ${JSON.stringify(strings.reduce((acc, s) => {
                     throw new Error(`Category 'frontend' is reserved for frontend messages, use any other category for backend messages`);
                 }
                 // console.log('🪲tr', msg, category, lang);
-                // if lang is not supported , throw
+                // if lang is not supported, fallback to primaryLanguage, then to english
                 if (!this.options.supportedLanguages.includes(lang)) {
-                    lang = 'en'; // for now simply fallback to english
-                    // throwing like line below might be too strict, e.g. for custom apis made with fetch which don't pass accept-language
-                    // throw new Error(`Language ${lang} is not entered to be supported by requested by browser in request headers accept-language`);
+                    lang = this.primaryLanguage; // fallback to primary language first
+                    if (!this.options.supportedLanguages.includes(lang)) {
+                        lang = 'en'; // final fallback to english
+                    }
                 }
                 let result;
                 // try to get translation from cache
@@ -753,7 +778,8 @@ ${JSON.stringify(strings.reduce((acc, s) => {
             const translations = {};
             const allTranslations = yield resource.list([Filters.EQ(this.options.categoryFieldName, category)]);
             for (const tr of allTranslations) {
-                translations[tr[this.enFieldName]] = tr[this.trFieldNames[lang]];
+                const translatedValue = tr[this.trFieldNames[lang]];
+                translations[tr[this.enFieldName]] = translatedValue || tr[this.enFieldName];
             }
             yield this.cache.set(cacheKey, translations);
             return translations;
@@ -764,8 +790,8 @@ ${JSON.stringify(strings.reduce((acc, s) => {
             return this.options.supportedLanguages.map((lang) => {
                 return {
                     code: lang,
-                    nameOnNative: iso6391.getNativeName(lang),
-                    nameEnglish: iso6391.getName(lang),
+                    nameOnNative: iso6391.getNativeName(getPrimaryLanguageCode(lang)),
+                    nameEnglish: iso6391.getName(getPrimaryLanguageCode(lang)),
                     emojiFlag: getCountryCodeFromLangCode(lang).toUpperCase().replace(/./g, char => String.fromCodePoint(char.charCodeAt(0) + 127397)),
                 };
             });

package/index.ts

@@ -1,7 +1,8 @@
 import AdminForth, { AdminForthPlugin, Filters, suggestIfTypo, AdminForthDataTypes, RAMLock } from "adminforth";
 import type { IAdminForth, IHttpServer, AdminForthComponentDeclaration, AdminForthResourceColumn, AdminForthResource, BeforeLoginConfirmationFunction, AdminForthConfigMenuItem } from "adminforth";
-import type { PluginOptions } from './types.js';
-import iso6391, { LanguageCode } from 'iso-639-1';
+import type { PluginOptions, SupportedLanguage } from './types.js';
+import iso6391 from 'iso-639-1';
+import { iso31661Alpha2ToAlpha3 } from 'iso-3166';
 import path from 'path';
 import fs from 'fs-extra';
 import chokidar from 'chokidar';
@@ -35,10 +36,30 @@ const countryISO31661ByLangISO6391 = {
   ur: 'pk', // Urdu → Pakistan
 };
 
-function getCountryCodeFromLangCode(langCode) {
+function getCountryCodeFromLangCode(lang: SupportedLanguage) {
+  const [langCode, region] = String(lang).split('-');
+  if (region && /^[A-Z]{2}$/.test(region)) {
+    return region.toLowerCase();
+  }
   return countryISO31661ByLangISO6391[langCode] || langCode;
 }
 
+function getPrimaryLanguageCode(langCode: SupportedLanguage): string {
+  return String(langCode).split('-')[0];
+}
+
+function isValidSupportedLanguageTag(langCode: SupportedLanguage): boolean {
+  const [primary, region] = String(langCode).split('-');
+  if (!iso6391.validate(primary as any)) {
+    return false;
+  }
+  if (!region) {
+    return true;
+  }
+  const regionUpper = region.toUpperCase();
+  return /^[A-Z]{2}$/.test(regionUpper) && (regionUpper in iso31661Alpha2ToAlpha3);
+}
+
 
 interface ICachingAdapter {
   get(key: string): Promise<any>;
@@ -84,7 +105,7 @@ export default class I18nPlugin extends AdminForthPlugin {
   passwordField: AdminForthResourceColumn;
   authResource: AdminForthResource;
   emailConfirmedField?: AdminForthResourceColumn;
-  trFieldNames: Partial<Record<LanguageCode, string>>;
+  trFieldNames: Partial<Record<SupportedLanguage, string>>;
   enFieldName: string;
   cache: ICachingAdapter;
   primaryKeyFieldName: string;
@@ -96,16 +117,18 @@ export default class I18nPlugin extends AdminForthPlugin {
 
   // sorted by name list of all supported languages, without en e.g. 'al|ro|uk'
   fullCompleatedFieldValue: string;
+  primaryLanguage: SupportedLanguage;
 
   constructor(options: PluginOptions) {
     super(options, import.meta.url);
     this.options = options;
     this.cache = new CachingAdapterMemory();
     this.trFieldNames = {};
+    this.primaryLanguage = options.primaryLanguage || 'en';
   }
 
   async computeCompletedFieldValue(record: any) {
-    return this.options.supportedLanguages.reduce((acc: string, lang: LanguageCode): string => {
+    return this.options.supportedLanguages.reduce((acc: string, lang: SupportedLanguage): string => {
       if (lang === 'en') {
         return acc;
       }
@@ -134,10 +157,10 @@ export default class I18nPlugin extends AdminForthPlugin {
   async modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
     super.modifyResourceConfig(adminforth, resourceConfig);
 
-    // check each supported language is valid ISO 639-1 code
+    // validate each supported language: ISO 639-1 or BCP-47 with region (e.g., en-GB)
     this.options.supportedLanguages.forEach((lang) => {
-      if (!iso6391.validate(lang)) {
-        throw new Error(`Invalid language code ${lang}, please define valid ISO 639-1 language code (2 lowercase letters)`);
+      if (!isValidSupportedLanguageTag(lang)) {
+        throw new Error(`Invalid language code ${lang}. Use ISO 639-1 (e.g., 'en') or BCP-47 with region (e.g., 'en-GB').`);
       }
     });
 
@@ -191,7 +214,7 @@ export default class I18nPlugin extends AdminForthPlugin {
 
     this.enFieldName = this.trFieldNames['en'] || 'en_string';
 
-    this.fullCompleatedFieldValue = this.options.supportedLanguages.reduce((acc: string, lang: LanguageCode) => {
+    this.fullCompleatedFieldValue = this.options.supportedLanguages.reduce((acc: string, lang: SupportedLanguage) => {
       if (lang === 'en') {
         return acc;
       }
@@ -269,11 +292,12 @@ export default class I18nPlugin extends AdminForthPlugin {
     const compMeta = { 
       brandSlug: adminforth.config.customization.brandNameSlug,
       pluginInstanceId: this.pluginInstanceId,
+      primaryLanguage: this.primaryLanguage,
       supportedLanguages: this.options.supportedLanguages.map(lang => (
         {
           code: lang,
           // lang name on on language native name
-          name: iso6391.getNativeName(lang),
+          name: iso6391.getNativeName(getPrimaryLanguageCode(lang)),
         }
       ))
     };
@@ -317,7 +341,7 @@ export default class I18nPlugin extends AdminForthPlugin {
     resourceConfig.hooks.edit.afterSave.push(async ({ updates, oldRecord }: { updates: any, oldRecord?: any }): Promise<{ ok: boolean, error?: string }> => {
       if (oldRecord) {
         // find lang which changed
-        let langsChanged: LanguageCode[] = [];
+        let langsChanged: SupportedLanguage[] = [];
         for (const lang of this.options.supportedLanguages) {
           if (lang === 'en') {
             continue;
@@ -473,7 +497,7 @@ export default class I18nPlugin extends AdminForthPlugin {
   }
 
   async translateToLang (
-      langIsoCode: LanguageCode, 
+      langIsoCode: SupportedLanguage, 
       strings: { en_string: string, category: string }[], 
       plurals=false,
       translations: any[],
@@ -495,25 +519,25 @@ export default class I18nPlugin extends AdminForthPlugin {
       return totalTranslated;
     }
     const lang = langIsoCode;
-    const langName = iso6391.getName(lang);
-    const requestSlavicPlurals = Object.keys(SLAVIC_PLURAL_EXAMPLES).includes(lang) && plurals;
-
+    const primaryLang = getPrimaryLanguageCode(lang);
+    const langName = iso6391.getName(primaryLang);
+    const requestSlavicPlurals = Object.keys(SLAVIC_PLURAL_EXAMPLES).includes(primaryLang) && plurals;
+    const region = String(lang).split('-')[1]?.toUpperCase() || '';
     const prompt = `
-I need to translate strings in JSON to ${langName} language (ISO 639-1 code ${lang}) from English for my web app.
-${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! If keys have variables (in curly brackets), then translated strings should have them as well (variables itself should not be translated). Here are the strings:
-
-\`\`\`json
-${
-JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object => {
-  acc[s.en_string] = '';
-  return acc;
-}, {}), null, 2)
-}
-\`\`\`
-`;  
-
-    process.env.HEAVY_DEBUG && console.log(`🪲🔪LLM prompt >> ${prompt.length}, <<${prompt} :\n\n`, JSON.stringify(prompt));
+        I need to translate strings in JSON to ${langName} language (ISO 639-1 code ${lang}) from English for my web app.
+        ${region ? `Use the regional conventions for ${lang} (region ${region}), including spelling, punctuation, and formatting.` : ''}
+        ${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! If keys have variables (in curly brackets), then translated strings should have them as well (variables itself should not be translated). Here are the strings:
+
+        \`\`\`json
+        ${
+        JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object => {
+          acc[s.en_string] = '';
+          return acc;
+        }, {}), null, 2)
+        }
+    \`\`\`
+    `;  
 
     // call OpenAI
     const resp = await this.options.completeAdapter.complete(
@@ -584,7 +608,7 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
 
     const needToTranslateByLang : Partial<
       Record<
-        LanguageCode,
+        SupportedLanguage,
         {
           en_string: string;
           category: string;
@@ -627,7 +651,7 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
 
     await Promise.all(
       Object.entries(needToTranslateByLang).map(
-        async ([lang, strings]: [LanguageCode, { en_string: string, category: string }[]]) => {
+        async ([lang, strings]: [SupportedLanguage, { en_string: string, category: string }[]]) => {
           // first translate without plurals
           const stringsWithoutPlurals = strings.filter(s => !s.en_string.includes('|'));
           const noPluralKeys = await this.translateToLang(lang, stringsWithoutPlurals, false, translations, updateStrings);
@@ -781,13 +805,13 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
         }
         // console.log('🪲tr', msg, category, lang);
 
-        // if lang is not supported , throw
-        if (!this.options.supportedLanguages.includes(lang as LanguageCode)) {
-          lang = 'en'; // for now simply fallback to english
-
-          // throwing like line below might be too strict, e.g. for custom apis made with fetch which don't pass accept-language
-          // throw new Error(`Language ${lang} is not entered to be supported by requested by browser in request headers accept-language`);
+      // if lang is not supported, fallback to primaryLanguage, then to english
+      if (!this.options.supportedLanguages.includes(lang as SupportedLanguage)) {
+        lang = this.primaryLanguage; // fallback to primary language first
+        if (!this.options.supportedLanguages.includes(lang as SupportedLanguage)) {
+          lang = 'en'; // final fallback to english
         }
+      }
 
         let result;
         // try to get translation from cache
@@ -885,23 +909,24 @@ JSON.stringify(strings.reduce((acc: object, s: { en_string: string }): object =>
     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]];
+      const translatedValue = tr[this.trFieldNames[lang]];
+      translations[tr[this.enFieldName]] = translatedValue || tr[this.enFieldName];
     }
     await this.cache.set(cacheKey, translations);
     return translations;
   }
 
   async languagesList(): Promise<{
-    code: LanguageCode;
+    code: SupportedLanguage;
     nameOnNative: string;
     nameEnglish: string;
     emojiFlag: string;
   }[]> {
     return this.options.supportedLanguages.map((lang) => {
       return {
-        code: lang as LanguageCode,
-        nameOnNative: iso6391.getNativeName(lang),
-        nameEnglish: iso6391.getName(lang),
+        code: lang,
+        nameOnNative: iso6391.getNativeName(getPrimaryLanguageCode(lang)),
+        nameEnglish: iso6391.getName(getPrimaryLanguageCode(lang)),
         emojiFlag: getCountryCodeFromLangCode(lang).toUpperCase().replace(/./g, char => String.fromCodePoint(char.charCodeAt(0) + 127397)),
       };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/i18n",
-  "version": "1.3.7",
+  "version": "1.4.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -28,6 +28,8 @@
     "@aws-sdk/client-ses": "^3.654.0",
     "@sapphire/async-queue": "^1.5.5",
     "chokidar": "^4.0.1",
+    "fs-extra": "^11.3.2",
+    "iso-3166": "^4.3.0",
     "iso-639-1": "^3.1.3"
   },
   "devDependencies": {

package/types.ts

@@ -1,17 +1,23 @@
 import { CompletionAdapter, EmailAdapter } from 'adminforth';
 import type { LanguageCode } from 'iso-639-1';
+import { iso31661Alpha2ToAlpha3 } from 'iso-3166';
 
 
+// BCP-47 support for types only: primary subtag is ISO 639-1, optional region
+type Alpha2Code = keyof typeof iso31661Alpha2ToAlpha3;
+type Bcp47LanguageTag = `${LanguageCode}-${Alpha2Code}`;
+export type SupportedLanguage = LanguageCode | Bcp47LanguageTag;
+
 export interface PluginOptions {
 
   /* List of ISO 639-1 language codes which you want to tsupport*/
-  supportedLanguages: LanguageCode[];
+  supportedLanguages: SupportedLanguage[];
 
   /**
    * Each translation string will be stored in a separate field, you can remap it to existing columns  using this option
    * By default it will assume field are named like `${lang_code}_string` (e.g. 'en_string', 'uk_string', 'ja_string', 'fr_string')
    */
-  translationFieldNames: Partial<Record<LanguageCode, string>>;
+  translationFieldNames: Partial<Record<SupportedLanguage, string>>;
 
   /**
    * Each string has a category, e.g. it might come from 'frontend' or some message from backend or column name on backend
@@ -49,4 +55,12 @@ export interface PluginOptions {
    * it should be a JSON field (underlyng database type should be TEXT or JSON)
    */
   reviewedCheckboxesFieldName?: string;
+
+  /**
+   * Primary language for the application. This is the default language shown to users.
+   * English is always used as the source language for translations, even if primaryLanguage is different.
+   * When a translation is missing for the primaryLanguage, English will be shown as fallback.
+   * Defaults to 'en' if not specified.
+   */
+  primaryLanguage?: SupportedLanguage;
 }