From dedb0426fb384c4b021642fa13677295cde37c19 Mon Sep 17 00:00:00 2001
From: Sivin Varghese <64252451+iamsivin@users.noreply.github.com>
Date: Thu, 27 Nov 2025 10:32:34 +0530
Subject: [PATCH] chore: Improve pagination with compact number formatting and
 pluralization (#12962)

---
 .../pagination/PaginationFooter.vue           |  32 +-
 .../dashboard/i18n/locale/en/companies.json   |   2 +-
 .../dashboard/i18n/locale/en/components.json  |   4 +-
 .../dashboard/i18n/locale/en/contact.json     |   2 +-
 .../composables/specs/useLocale.spec.js       | 188 +++++++++
 .../specs/useNumberFormatter.spec.js          | 364 ++++++++++++++++++
 .../shared/composables/useLocale.js           |  57 +++
 .../shared/composables/useNumberFormatter.js  |  67 ++++
 8 files changed, 701 insertions(+), 15 deletions(-)
 create mode 100644 app/javascript/shared/composables/specs/useLocale.spec.js
 create mode 100644 app/javascript/shared/composables/specs/useNumberFormatter.spec.js
 create mode 100644 app/javascript/shared/composables/useLocale.js
 create mode 100644 app/javascript/shared/composables/useNumberFormatter.js

diff --git a/app/javascript/dashboard/components-next/pagination/PaginationFooter.vue b/app/javascript/dashboard/components-next/pagination/PaginationFooter.vue
index e58b2db86..0a919dbbf 100644
--- a/app/javascript/dashboard/components-next/pagination/PaginationFooter.vue
+++ b/app/javascript/dashboard/components-next/pagination/PaginationFooter.vue
@@ -1,6 +1,7 @@
 <script setup>
 import { computed } from 'vue';
 import { useI18n } from 'vue-i18n';
+import { useNumberFormatter } from 'shared/composables/useNumberFormatter';
 
 import Button from 'dashboard/components-next/button/Button.vue';
 
@@ -24,6 +25,7 @@ const props = defineProps({
 });
 const emit = defineEmits(['update:currentPage']);
 const { t } = useI18n();
+const { formatCompactNumber, formatFullNumber } = useNumberFormatter();
 
 const totalPages = computed(() =>
   Math.ceil(props.totalItems / props.itemsPerPage)
@@ -43,21 +45,27 @@ const changePage = newPage => {
 };
 
 const currentPageInformation = computed(() => {
+  const translationKey = props.currentPageInfo || 'PAGINATION_FOOTER.SHOWING';
   return t(
-    props.currentPageInfo ? props.currentPageInfo : 'PAGINATION_FOOTER.SHOWING',
+    translationKey,
     {
-      startItem: startItem.value,
-      endItem: endItem.value,
-      totalItems: props.totalItems,
-    }
+      startItem: formatFullNumber(startItem.value),
+      endItem: formatFullNumber(endItem.value),
+      totalItems: formatCompactNumber(props.totalItems),
+    },
+    Number(props.totalItems)
   );
 });
 
 const pageInfo = computed(() => {
-  return t('PAGINATION_FOOTER.CURRENT_PAGE_INFO', {
-    currentPage: '',
-    totalPages: totalPages.value,
-  });
+  return t(
+    'PAGINATION_FOOTER.CURRENT_PAGE_INFO',
+    {
+      currentPage: '',
+      totalPages: formatCompactNumber(totalPages.value),
+    },
+    Number(totalPages.value)
+  );
 });
 </script>
 
@@ -91,9 +99,11 @@ const pageInfo = computed(() => {
       />
       <div class="inline-flex items-center gap-2 text-sm text-n-slate-11">
         <span class="px-3 tabular-nums py-0.5 bg-n-alpha-black2 rounded-md">
-          {{ currentPage }}
+          {{ formatFullNumber(currentPage) }}
+        </span>
+        <span class="truncate">
+          {{ pageInfo }}
         </span>
-        <span class="truncate">{{ pageInfo }}</span>
       </div>
       <Button
         icon="i-lucide-chevron-right"
diff --git a/app/javascript/dashboard/i18n/locale/en/companies.json b/app/javascript/dashboard/i18n/locale/en/companies.json
index 57f7b171d..86190831b 100644
--- a/app/javascript/dashboard/i18n/locale/en/companies.json
+++ b/app/javascript/dashboard/i18n/locale/en/companies.json
@@ -26,7 +26,7 @@
   },
   "COMPANIES_LAYOUT": {
     "PAGINATION_FOOTER": {
-      "SHOWING": "Showing {startItem} - {endItem} of {totalItems} companies"
+      "SHOWING": "Showing {startItem} – {endItem} of {totalItems} company | Showing {startItem} – {endItem} of {totalItems} companies"
     }
   }
 }
diff --git a/app/javascript/dashboard/i18n/locale/en/components.json b/app/javascript/dashboard/i18n/locale/en/components.json
index 0a2542a84..7793b419f 100644
--- a/app/javascript/dashboard/i18n/locale/en/components.json
+++ b/app/javascript/dashboard/i18n/locale/en/components.json
@@ -1,7 +1,7 @@
 {
   "PAGINATION_FOOTER": {
-    "SHOWING": "Showing {startItem} - {endItem} of {totalItems} items",
-    "CURRENT_PAGE_INFO": "{currentPage} of {totalPages} pages"
+    "SHOWING": "Showing {startItem} - {endItem} of {totalItems} item | Showing {startItem} - {endItem} of {totalItems} items",
+    "CURRENT_PAGE_INFO": "{currentPage} of {totalPages} page | {currentPage} of {totalPages} pages"
   },
   "COMBOBOX": {
     "PLACEHOLDER": "Select an option...",
diff --git a/app/javascript/dashboard/i18n/locale/en/contact.json b/app/javascript/dashboard/i18n/locale/en/contact.json
index 4de5f51cd..e324e1951 100644
--- a/app/javascript/dashboard/i18n/locale/en/contact.json
+++ b/app/javascript/dashboard/i18n/locale/en/contact.json
@@ -377,7 +377,7 @@
       }
     },
     "PAGINATION_FOOTER": {
-      "SHOWING": "Showing {startItem} - {endItem} of {totalItems} contacts"
+      "SHOWING": "Showing {startItem} - {endItem} of {totalItems} contact | Showing {startItem} - {endItem} of {totalItems} contacts"
     },
     "FILTER": {
       "NAME": "Name",
diff --git a/app/javascript/shared/composables/specs/useLocale.spec.js b/app/javascript/shared/composables/specs/useLocale.spec.js
new file mode 100644
index 000000000..2b9f04b9d
--- /dev/null
+++ b/app/javascript/shared/composables/specs/useLocale.spec.js
@@ -0,0 +1,188 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { useLocale } from '../useLocale';
+import { useI18n } from 'vue-i18n';
+import { ref } from 'vue';
+
+vi.mock('vue-i18n');
+
+describe('useLocale', () => {
+  beforeEach(() => {
+    vi.mocked(useI18n).mockReturnValue({
+      locale: ref('en-US'),
+    });
+  });
+
+  describe('resolvedLocale', () => {
+    it('should return normalized locale for valid hyphen-based tags', () => {
+      const mockLocale = ref('en-US');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+      expect(resolvedLocale.value).toBe('en-US');
+    });
+
+    it('should normalize underscore-based locale tags to hyphens', () => {
+      const mockLocale = ref('pt_BR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+      // Should normalize pt_BR to pt-BR
+      expect(resolvedLocale.value).toMatch(/^pt(-BR)?$/);
+    });
+
+    it('should normalize zh_CN to zh-CN or fall back to zh', () => {
+      const mockLocale = ref('zh_CN');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+      // Should normalize zh_CN to zh-CN or fall back to zh
+      expect(resolvedLocale.value).toMatch(/^zh(-CN)?$/);
+    });
+
+    it('should normalize en_US to en-US or fall back to en', () => {
+      const mockLocale = ref('en_US');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+      // Should normalize en_US to en-US or fall back to en
+      expect(resolvedLocale.value).toMatch(/^en(-US)?$/);
+    });
+
+    it('should fall back to base language when specific locale not supported', () => {
+      // Use a specific locale that might not be fully supported
+      const mockLocale = ref('pt-BR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+      // Should return either pt-BR or pt (base language)
+      expect(resolvedLocale.value).toMatch(/^pt(-BR)?$/);
+    });
+
+    it('should fall back to English for completely unsupported locales', () => {
+      const mockLocale = ref('xx-YY');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+      // Should fall back to 'en'
+      expect(resolvedLocale.value).toBe('en');
+    });
+
+    it('should handle null locale gracefully', () => {
+      const mockLocale = ref(null);
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+      // Should fall back to 'en'
+      expect(resolvedLocale.value).toBe('en');
+    });
+
+    it('should handle undefined locale gracefully', () => {
+      const mockLocale = ref(undefined);
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+      // Should fall back to 'en'
+      expect(resolvedLocale.value).toBe('en');
+    });
+
+    it('should handle base language code without region', () => {
+      const mockLocale = ref('pt');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+      // Should work with base language
+      expect(resolvedLocale.value).toBe('pt');
+    });
+
+    it('should handle multiple underscores in locale tag', () => {
+      const mockLocale = ref('zh_Hans_CN');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+      // Should normalize all underscores to hyphens
+      expect(resolvedLocale.value).toMatch(/^zh(-Hans-CN|-Hans|-CN)?$/);
+    });
+
+    it('should be reactive to locale changes', () => {
+      const mockLocale = ref('en-US');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+
+      expect(resolvedLocale.value).toBe('en-US');
+
+      // Change locale
+      mockLocale.value = 'pt_BR';
+
+      // Should update reactively
+      expect(resolvedLocale.value).toMatch(/^pt(-BR)?$/);
+    });
+
+    it('should work with common locales', () => {
+      const testCases = [
+        { input: 'de-DE', expected: /^de(-DE)?$/ },
+        { input: 'fr-FR', expected: /^fr(-FR)?$/ },
+        { input: 'es-ES', expected: /^es(-ES)?$/ },
+        { input: 'ja-JP', expected: /^ja(-JP)?$/ },
+        { input: 'ko-KR', expected: /^ko(-KR)?$/ },
+        { input: 'ar-SA', expected: /^ar(-SA)?$/ },
+        { input: 'hi-IN', expected: /^hi(-IN)?$/ },
+        { input: 'ru-RU', expected: /^ru(-RU)?$/ },
+        { input: 'tr-TR', expected: /^tr(-TR)?$/ },
+      ];
+
+      testCases.forEach(({ input, expected }) => {
+        const mockLocale = ref(input);
+        vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+        const { resolvedLocale } = useLocale();
+        expect(resolvedLocale.value).toMatch(expected);
+      });
+    });
+  });
+
+  describe('locale (raw)', () => {
+    it('should expose raw locale value', () => {
+      const mockLocale = ref('pt_BR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { locale } = useLocale();
+      // Raw locale should be unchanged
+      expect(locale.value).toBe('pt_BR');
+    });
+
+    it('should be reactive', () => {
+      const mockLocale = ref('en-US');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { locale } = useLocale();
+
+      expect(locale.value).toBe('en-US');
+
+      mockLocale.value = 'pt-BR';
+
+      expect(locale.value).toBe('pt-BR');
+    });
+  });
+
+  describe('Intl API compatibility', () => {
+    it('should work with Intl.NumberFormat', () => {
+      const mockLocale = ref('pt_BR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+
+      // Should not throw error
+      expect(() => {
+        new Intl.NumberFormat(resolvedLocale.value).format(1234567);
+      }).not.toThrow();
+    });
+
+    it('should work with Intl.DateTimeFormat', () => {
+      const mockLocale = ref('zh_CN');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+
+      // Should not throw error
+      expect(() => {
+        new Intl.DateTimeFormat(resolvedLocale.value).format(new Date());
+      }).not.toThrow();
+    });
+
+    it('should work with Intl.Collator', () => {
+      const mockLocale = ref('en_US');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { resolvedLocale } = useLocale();
+
+      // Should not throw error
+      expect(() => {
+        new Intl.Collator(resolvedLocale.value).compare('a', 'b');
+      }).not.toThrow();
+    });
+  });
+});
diff --git a/app/javascript/shared/composables/specs/useNumberFormatter.spec.js b/app/javascript/shared/composables/specs/useNumberFormatter.spec.js
new file mode 100644
index 000000000..3a9b8d41b
--- /dev/null
+++ b/app/javascript/shared/composables/specs/useNumberFormatter.spec.js
@@ -0,0 +1,364 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { useNumberFormatter } from '../useNumberFormatter';
+import { useI18n } from 'vue-i18n';
+import { ref } from 'vue';
+
+vi.mock('vue-i18n');
+
+describe('useNumberFormatter', () => {
+  beforeEach(() => {
+    vi.mocked(useI18n).mockReturnValue({
+      locale: ref('en-US'),
+    });
+  });
+
+  describe('formatCompactNumber', () => {
+    it('should return exact numbers for values under 1,000', () => {
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(0)).toBe('0');
+      expect(formatCompactNumber(1)).toBe('1');
+      expect(formatCompactNumber(42)).toBe('42');
+      expect(formatCompactNumber(999)).toBe('999');
+    });
+
+    it('should return "Xk" for exact thousands and "Xk+" for values with remainder', () => {
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(1000)).toBe('1k');
+      expect(formatCompactNumber(1020)).toBe('1k+');
+      expect(formatCompactNumber(1500)).toBe('1k+');
+      expect(formatCompactNumber(1999)).toBe('1k+');
+      expect(formatCompactNumber(2000)).toBe('2k');
+      expect(formatCompactNumber(15000)).toBe('15k');
+      expect(formatCompactNumber(15500)).toBe('15k+');
+      expect(formatCompactNumber(999999)).toBe('999k+');
+    });
+
+    it('should return millions/billion/trillion format for values 1,000,000 and above', () => {
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(1000000)).toBe('1M');
+      expect(formatCompactNumber(1000001)).toBe('1.0M');
+      expect(formatCompactNumber(1200000)).toBe('1.2M');
+      expect(formatCompactNumber(1234000)).toBe('1.2M');
+      expect(formatCompactNumber(2500000)).toBe('2.5M');
+      expect(formatCompactNumber(10000000)).toBe('10M');
+      expect(formatCompactNumber(1000000000)).toBe('1B');
+      expect(formatCompactNumber(1100000000)).toBe('1.1B');
+      expect(formatCompactNumber(10000000000)).toBe('10B');
+      expect(formatCompactNumber(11000000000)).toBe('11B');
+      expect(formatCompactNumber(1000000000000)).toBe('1T');
+      expect(formatCompactNumber(1100000000000)).toBe('1.1T');
+      expect(formatCompactNumber(10000000000000)).toBe('10T');
+      expect(formatCompactNumber(11000000000000)).toBe('11T');
+    });
+
+    it('should handle edge cases gracefully', () => {
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(null)).toBe('0');
+      expect(formatCompactNumber(undefined)).toBe('0');
+      expect(formatCompactNumber(NaN)).toBe('0');
+      expect(formatCompactNumber('string')).toBe('0');
+    });
+
+    it('should handle negative numbers', () => {
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(-500)).toBe('-500');
+      expect(formatCompactNumber(-1000)).toBe('-1k');
+      expect(formatCompactNumber(-1500)).toBe('-1k+');
+      expect(formatCompactNumber(-2000)).toBe('-2k');
+      expect(formatCompactNumber(-1200000)).toBe('-1.2M');
+    });
+
+    it('should format with en-US locale', () => {
+      const mockLocale = ref('en-US');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(1500)).toBe('1k+');
+    });
+
+    it('should format with de-DE locale', () => {
+      const mockLocale = ref('de-DE');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(2000)).toBe('2k');
+    });
+
+    it('should format with fr-FR locale (compact notation)', () => {
+      const mockLocale = ref('fr-FR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      const result = formatCompactNumber(1000000);
+      expect(result).toMatch(/1\s*M/); // French uses space before M
+    });
+
+    it('should format with ja-JP locale', () => {
+      const mockLocale = ref('ja-JP');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(999)).toBe('999');
+    });
+
+    it('should format with ar-SA locale (Arabic numerals)', () => {
+      const mockLocale = ref('ar-SA');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      const result = formatCompactNumber(5000);
+      expect(result).toContain('k');
+      expect(typeof result).toBe('string');
+    });
+
+    it('should format with es-ES locale', () => {
+      const mockLocale = ref('es-ES');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(7500)).toBe('7k+');
+    });
+
+    it('should format with hi-IN locale', () => {
+      const mockLocale = ref('hi-IN');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(100000)).toBe('100k');
+    });
+
+    it('should format with ru-RU locale', () => {
+      const mockLocale = ref('ru-RU');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(3000)).toBe('3k');
+    });
+
+    it('should format with ko-KR locale (uses 만 for 10,000)', () => {
+      const mockLocale = ref('ko-KR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      const result = formatCompactNumber(2500000);
+      expect(result).toContain('만'); // Korean uses 만 (10,000) as a unit, so 2,500,000 should contain 만
+    });
+
+    it('should format with pt-BR locale', () => {
+      const mockLocale = ref('pt-BR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      expect(formatCompactNumber(8888)).toBe('8k+');
+    });
+
+    it('should handle underscore-based locale tags (pt_BR)', () => {
+      const mockLocale = ref('pt_BR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      // Should normalize pt_BR to pt-BR and work correctly
+      expect(formatCompactNumber(8888)).toBe('8k+');
+      expect(formatCompactNumber(1000000)).toBe('1\u00a0mi');
+    });
+
+    it('should handle underscore-based locale tags (zh_CN)', () => {
+      const mockLocale = ref('zh_CN');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      // Should normalize zh_CN to zh-CN and work correctly
+      expect(formatCompactNumber(999)).toBe('999');
+      expect(formatCompactNumber(5000)).toBe('5k');
+    });
+
+    it('should handle underscore-based locale tags (en_US)', () => {
+      const mockLocale = ref('en_US');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      // Should normalize en_US to en-US and work correctly
+      expect(formatCompactNumber(1500)).toBe('1k+');
+      expect(formatCompactNumber(1000000)).toBe('1M');
+    });
+
+    it('should handle null/undefined locale gracefully', () => {
+      const mockLocale = ref(null);
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      // Should fall back to 'en' locale
+      expect(formatCompactNumber(1500)).toBe('1k+');
+    });
+
+    it('should fall back to base language when specific locale not supported', () => {
+      // Simulate a case where pt-BR might not be fully supported but pt is
+      const mockLocale = ref('pt-BR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      // Should work with either pt-BR or pt fallback
+      const result = formatCompactNumber(1500);
+      expect(result).toMatch(/1k\+/);
+    });
+
+    it('should fall back to English for completely unsupported locales', () => {
+      // Use a completely made-up locale
+      const mockLocale = ref('xx-YY');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      // Should fall back to 'en' and work
+      expect(formatCompactNumber(1500)).toBe('1k+');
+      expect(formatCompactNumber(1000000)).toBe('1M');
+    });
+
+    it('should handle edge case with only base language code', () => {
+      const mockLocale = ref('pt');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatCompactNumber } = useNumberFormatter();
+      // Should work with base language
+      expect(formatCompactNumber(2000)).toBe('2k');
+    });
+  });
+
+  describe('formatFullNumber', () => {
+    it('should format numbers with locale-specific formatting', () => {
+      const { formatFullNumber } = useNumberFormatter();
+      expect(formatFullNumber(1000)).toBe('1,000');
+      expect(formatFullNumber(1234567)).toBe('1,234,567');
+      expect(formatFullNumber(1234567890)).toBe('1,234,567,890');
+      expect(formatFullNumber(1234567890123)).toBe('1,234,567,890,123');
+    });
+
+    it('should handle edge cases gracefully', () => {
+      const { formatFullNumber } = useNumberFormatter();
+      expect(formatFullNumber(null)).toBe('0');
+      expect(formatFullNumber(undefined)).toBe('0');
+      expect(formatFullNumber(NaN)).toBe('0');
+      expect(formatFullNumber('string')).toBe('0');
+    });
+
+    it('should format with en-US locale (comma separator)', () => {
+      const mockLocale = ref('en-US');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      expect(formatFullNumber(1234567)).toBe('1,234,567');
+    });
+
+    it('should format with de-DE locale (period separator)', () => {
+      const mockLocale = ref('de-DE');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      expect(formatFullNumber(9876543)).toBe('9.876.543');
+    });
+
+    it('should format with es-ES locale (period separator)', () => {
+      const mockLocale = ref('es-ES');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      expect(formatFullNumber(5555555)).toBe('5.555.555');
+    });
+
+    it('should format with zh-CN locale', () => {
+      const mockLocale = ref('zh-CN');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      expect(formatFullNumber(1000000)).toBe('1,000,000');
+    });
+
+    it('should format with ar-EG locale (Arabic numerals, RTL)', () => {
+      const mockLocale = ref('ar-EG');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      const result = formatFullNumber(7654321);
+      // Arabic locale uses Eastern Arabic numerals (٠-٩)
+      // Just verify it's formatted (length should be reasonable)
+      expect(result.length).toBeGreaterThan(6);
+    });
+
+    it('should format with fr-FR locale (narrow no-break space)', () => {
+      const mockLocale = ref('fr-FR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      const result = formatFullNumber(3333333);
+      expect(result).toContain('3');
+      expect(result).toContain('333');
+    });
+
+    it('should format with hi-IN locale (Indian numbering system)', () => {
+      const mockLocale = ref('hi-IN');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      expect(formatFullNumber(9999999)).toBe('99,99,999');
+    });
+
+    it('should format with th-TH locale', () => {
+      const mockLocale = ref('th-TH');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      expect(formatFullNumber(4444444)).toBe('4,444,444');
+    });
+
+    it('should format with tr-TR locale', () => {
+      const mockLocale = ref('tr-TR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      expect(formatFullNumber(6666666)).toBe('6.666.666');
+    });
+
+    it('should format with pt-PT locale (space separator)', () => {
+      const mockLocale = ref('pt-PT');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      const result = formatFullNumber(2222222);
+      // Portuguese (Portugal) uses narrow no-break space as separator
+      expect(result).toMatch(/2[\s\u202f]222[\s\u202f]222/);
+    });
+
+    it('should handle underscore-based locale tags (pt_BR)', () => {
+      const mockLocale = ref('pt_BR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      // Should normalize pt_BR to pt-BR and work correctly
+      expect(formatFullNumber(1234567)).toBe('1.234.567');
+    });
+
+    it('should handle underscore-based locale tags (zh_CN)', () => {
+      const mockLocale = ref('zh_CN');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      // Should normalize zh_CN to zh-CN and work correctly
+      expect(formatFullNumber(1000000)).toBe('1,000,000');
+    });
+
+    it('should handle underscore-based locale tags (en_US)', () => {
+      const mockLocale = ref('en_US');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      // Should normalize en_US to en-US and work correctly
+      expect(formatFullNumber(1234567)).toBe('1,234,567');
+    });
+
+    it('should handle null/undefined locale gracefully', () => {
+      const mockLocale = ref(null);
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      // Should fall back to 'en' locale
+      expect(formatFullNumber(1234567)).toBe('1,234,567');
+    });
+
+    it('should fall back to base language when specific locale not supported', () => {
+      // Simulate a case where pt-BR might not be fully supported but pt is
+      const mockLocale = ref('pt-BR');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      // Should work with either pt-BR or pt fallback
+      const result = formatFullNumber(1234567);
+      // Portuguese uses period as thousands separator
+      expect(result).toMatch(/1[.,\s]234[.,\s]567/);
+    });
+
+    it('should fall back to English for completely unsupported locales', () => {
+      // Use a completely made-up locale
+      const mockLocale = ref('xx-YY');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      // Should fall back to 'en' and work
+      expect(formatFullNumber(1234567)).toBe('1,234,567');
+    });
+
+    it('should handle edge case with only base language code', () => {
+      const mockLocale = ref('pt');
+      vi.mocked(useI18n).mockReturnValue({ locale: mockLocale });
+      const { formatFullNumber } = useNumberFormatter();
+      // Should work with base language
+      const result = formatFullNumber(1000000);
+      expect(result).toMatch(/1[.,\s]000[.,\s]000/);
+    });
+  });
+});
diff --git a/app/javascript/shared/composables/useLocale.js b/app/javascript/shared/composables/useLocale.js
new file mode 100644
index 000000000..b496d15dd
--- /dev/null
+++ b/app/javascript/shared/composables/useLocale.js
@@ -0,0 +1,57 @@
+import { computed } from 'vue';
+import { useI18n } from 'vue-i18n';
+
+/**
+ * Composable for locale resolution and validation
+ * Provides a normalized, validated locale that works with Intl APIs
+ */
+export function useLocale() {
+  const { locale } = useI18n();
+
+  /**
+   * Resolves and validates the current locale for use with Intl APIs
+   *
+   * Handles multiple fallback scenarios:
+   * 1. Normalizes underscore-based tags (pt_BR → pt-BR, zh_CN → zh-CN)
+   * 2. Falls back to base language if specific locale unsupported (pt-BR → pt)
+   * 3. Falls back to English if base language unsupported (xx-YY → en)
+   *
+   * @returns {string} Valid BCP 47 locale tag for Intl APIs
+   *
+   * @example
+   * const { resolvedLocale } = useLocale();
+   * new Intl.NumberFormat(resolvedLocale.value).format(1234);
+   * new Intl.DateTimeFormat(resolvedLocale.value).format(new Date());
+   */
+  const resolvedLocale = computed(() => {
+    // Handle null/undefined locale
+    if (!locale.value) return 'en';
+
+    // Normalize underscore to hyphen (pt_BR → pt-BR, zh_CN → zh-CN)
+    const normalized = locale.value.replace(/_/g, '-');
+
+    // Check if the specific locale is supported (e.g., pt-BR, zh-CN)
+    const supportedLocales = Intl.NumberFormat.supportedLocalesOf([normalized]);
+    if (supportedLocales.length > 0) {
+      return normalized;
+    }
+
+    // If specific locale not supported, try base language (pt-BR → pt, zh-CN → zh)
+    const baseLocale = normalized.split('-')[0];
+    const baseSupportedLocales = Intl.NumberFormat.supportedLocalesOf([
+      baseLocale,
+    ]);
+    if (baseSupportedLocales.length > 0) {
+      return baseLocale;
+    }
+
+    // If base language also not supported, fall back to English
+    return 'en';
+  });
+
+  return {
+    resolvedLocale,
+    // Also expose the raw locale for cases where you need it
+    locale,
+  };
+}
diff --git a/app/javascript/shared/composables/useNumberFormatter.js b/app/javascript/shared/composables/useNumberFormatter.js
new file mode 100644
index 000000000..54ded0e93
--- /dev/null
+++ b/app/javascript/shared/composables/useNumberFormatter.js
@@ -0,0 +1,67 @@
+import { useLocale } from './useLocale';
+
+/**
+ * Composable for number formatting with i18n locale support
+ * Provides methods to format numbers in compact and full display formats
+ */
+export function useNumberFormatter() {
+  const { resolvedLocale } = useLocale();
+
+  /**
+   * Formats numbers for display with clean, minimal formatting
+   * - Up to 1,000: show exact number (e.g., 999)
+   * - 1,000 to 999,999: show as "Xk" for exact thousands or "Xk+" for remainder (e.g., 1000 → "1k", 1500 → "1k+")
+   * - 1,000,000+: show in millions with 1 decimal place (e.g., 1,234,000 → "1.2M")
+   *
+   * Uses browser-native Intl.NumberFormat with proper i18n locale support
+   *
+   * @param {number} num - The number to format
+   * @returns {string} Formatted number string
+   */
+  const formatCompactNumber = num => {
+    if (typeof num !== 'number' || Number.isNaN(num)) {
+      return '0';
+    }
+
+    // For numbers between -1000 and 1000 (exclusive), show exact number with locale formatting
+    if (Math.abs(num) < 1000) {
+      return new Intl.NumberFormat(resolvedLocale.value).format(num);
+    }
+
+    // For numbers with absolute value above 1,000,000, show in millions with 1 decimal place
+    if (Math.abs(num) >= 1000000) {
+      const millions = num / 1000000;
+      return new Intl.NumberFormat(resolvedLocale.value, {
+        notation: 'compact',
+        compactDisplay: 'short',
+        maximumFractionDigits: 1,
+        minimumFractionDigits: millions % 1 === 0 ? 0 : 1,
+      }).format(num);
+    }
+
+    // For numbers with absolute value between 1,000 and 1,000,000, show as "Xk" or "Xk+" using floor value
+    // For negative numbers, we want to floor towards zero (truncate), not towards negative infinity
+    const thousands = num >= 0 ? Math.floor(num / 1000) : Math.ceil(num / 1000);
+    const remainder = Math.abs(num) % 1000;
+    const suffix = remainder === 0 ? 'k' : 'k+';
+    return `${new Intl.NumberFormat(resolvedLocale.value).format(thousands)}${suffix}`;
+  };
+
+  /**
+   * Format a number for full display with locale-specific formatting
+   * @param {number} num - The number to format
+   * @returns {string} Formatted number string with full precision and locale formatting (e.g., 1,234,567)
+   */
+  const formatFullNumber = num => {
+    if (typeof num !== 'number' || Number.isNaN(num)) {
+      return '0';
+    }
+
+    return new Intl.NumberFormat(resolvedLocale.value).format(num);
+  };
+
+  return {
+    formatCompactNumber,
+    formatFullNumber,
+  };
+}