feat(KAN-16): add English localization foundation

resources/js/app.ts

@@ -4,6 +4,7 @@ import type { DefineComponent } from 'vue';
 import { createApp, h } from 'vue';
 import '../css/app.css';
 import { initializeTheme } from '@/composables/useAppearance';
+import { createLocalization } from '@/lib/localization';
 
 const appName = import.meta.env.VITE_APP_NAME || 'Laravel';
 
@@ -17,6 +18,7 @@ createInertiaApp({
     setup({ el, App, props, plugin }) {
         createApp({ render: () => h(App, props) })
             .use(plugin)
+            .use(createLocalization(props.initialPage.props.localization))
             .mount(el);
     },
     progress: {

resources/js/components/AlertError.vue

@@ -2,15 +2,15 @@
 import { AlertCircle } from 'lucide-vue-next';
 import { computed } from 'vue';
 import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import { useLocalization } from '@/composables/useLocalization';
 
 type Props = {
     errors: string[];
     title?: string;
 };
 
-const props = withDefaults(defineProps<Props>(), {
-    title: 'Something went wrong.',
-});
+const props = defineProps<Props>();
+const { t } = useLocalization();
 
 const uniqueErrors = computed(() => Array.from(new Set(props.errors)));
 </script>
@@ -18,7 +18,7 @@ const uniqueErrors = computed(() => Array.from(new Set(props.errors)));
 <template>
     <Alert variant="destructive">
         <AlertCircle class="size-4" />
-        <AlertTitle>{{ title }}</AlertTitle>
+        <AlertTitle>{{ title ?? t('common.error') }}</AlertTitle>
         <AlertDescription>
             <ul class="list-inside list-disc text-sm">
                 <li v-for="(error, index) in uniqueErrors" :key="index">

resources/js/composables/useLocalization.ts

@@ -0,0 +1,12 @@
+import { inject } from 'vue';
+import { localizationKey } from '@/lib/localization';
+
+export function useLocalization() {
+    const localization = inject(localizationKey);
+    if (!localization) {
+        throw new Error(
+            'The localization plugin must be installed before useLocalization().',
+        );
+    }
+    return localization;
+}

resources/js/lib/localization.ts

@@ -0,0 +1,159 @@
+import { readonly, ref } from 'vue';
+import type { App, InjectionKey } from 'vue';
+import { en } from '@/locales/en';
+import type {
+    LocalizationSettings,
+    TranslationCatalog,
+    TranslationKey,
+    TranslationParameters,
+} from '@/types/localization';
+
+const defaultLocale = 'en';
+const catalogs: Record<string, TranslationCatalog> = { en };
+
+function placeholders(message: string): string[] {
+    return [
+        ...new Set(
+            [...message.matchAll(/\{(\w+)\}/g)].map((match) => match[1]),
+        ),
+    ].sort();
+}
+
+/** Validate every catalog, including messages that no component has rendered yet. */
+export function validateCatalog(catalog: TranslationCatalog): void {
+    for (const key of Object.keys(en) as TranslationKey[]) {
+        const message = Object.hasOwn(catalog, key) ? catalog[key] : undefined;
+        const source = en[key];
+
+        if (message === undefined || typeof message !== typeof source) {
+            throw new Error(`Missing or invalid translation: ${key}`);
+        }
+
+        const expected = placeholders(
+            typeof source === 'string' ? source : source.other,
+        );
+        const forms =
+            typeof message === 'string'
+                ? [message]
+                : Object.values(message ?? {});
+
+        if (
+            typeof message !== 'string' &&
+            (!message || typeof message.other !== 'string')
+        ) {
+            throw new Error(`Missing plural fallback: ${key}`);
+        }
+
+        for (const form of forms) {
+            if (
+                typeof form !== 'string' ||
+                form.trim() === '' ||
+                JSON.stringify(placeholders(form)) !== JSON.stringify(expected)
+            ) {
+                throw new Error(`Invalid translation placeholders: ${key}`);
+            }
+        }
+    }
+}
+
+export function createLocalization(
+    settings: Partial<LocalizationSettings> = {},
+    availableCatalogs: Record<string, TranslationCatalog> = catalogs,
+) {
+    const messages: Record<string, TranslationCatalog> = {
+        ...availableCatalogs,
+        en,
+    };
+    for (const catalog of Object.values(messages)) {
+        validateCatalog(catalog);
+    }
+
+    function resolveLocale(requested: string): string {
+        try {
+            const [canonical] = Intl.getCanonicalLocales(
+                requested.replaceAll('_', '-'),
+            );
+            if (Object.hasOwn(messages, canonical)) {
+                return canonical;
+            }
+            const language = canonical.split('-')[0];
+            return Object.hasOwn(messages, language) ? language : defaultLocale;
+        } catch {
+            return defaultLocale;
+        }
+    }
+
+    const locale = ref(resolveLocale(settings.locale ?? defaultLocale));
+    const timeZone = settings.timeZone ?? 'UTC';
+
+    function number(
+        value: number,
+        options: Intl.NumberFormatOptions = {},
+    ): string {
+        return new Intl.NumberFormat(locale.value, options).format(value);
+    }
+
+    function date(
+        value: Date | number,
+        options: Intl.DateTimeFormatOptions = {},
+    ): string {
+        return new Intl.DateTimeFormat(locale.value, {
+            timeZone,
+            ...options,
+        }).format(value);
+    }
+
+    /** Interpolate plain text only; render with Vue text bindings, never v-html. */
+    function t(
+        key: TranslationKey,
+        parameters: TranslationParameters = {},
+    ): string {
+        const catalog = messages[locale.value];
+        if (!Object.hasOwn(catalog, key)) {
+            throw new Error(`Missing translation: ${key}`);
+        }
+
+        const message = catalog[key];
+        let template: string;
+        if (typeof message === 'string') {
+            template = message;
+        } else {
+            const count = parameters.count;
+            if (typeof count !== 'number' || !Number.isFinite(count)) {
+                throw new Error(`Translation requires a finite count: ${key}`);
+            }
+            template =
+                message[new Intl.PluralRules(locale.value).select(count)] ??
+                message.other;
+        }
+
+        return template.replace(/\{(\w+)\}/g, (_, name: string) => {
+            if (!Object.hasOwn(parameters, name)) {
+                throw new Error(
+                    `Missing translation parameter: ${key}.${name}`,
+                );
+            }
+            const value = parameters[name];
+            return typeof value === 'number' ? number(value) : value;
+        });
+    }
+
+    const localization = {
+        locale: readonly(locale),
+        t,
+        number,
+        date,
+        setLocale(requested: string): void {
+            locale.value = resolveLocale(requested);
+        },
+        install(app: App): void {
+            app.provide(localizationKey, localization);
+        },
+    };
+
+    return localization;
+}
+
+export type Localization = ReturnType<typeof createLocalization>;
+export const localizationKey: InjectionKey<Localization> =
+    Symbol('localization');

resources/js/locales/en.ts

@@ -0,0 +1,11 @@
+export const en = {
+    'common.cancel': 'Cancel',
+    'common.save': 'Save',
+    'common.loading': 'Loading…',
+    'common.error': 'Something went wrong.',
+    'pagination.page': 'Page {page} of {total}',
+    'tickets.count': {
+        one: '{count} ticket',
+        other: '{count} tickets',
+    },
+} as const;

resources/js/ssr.ts

@@ -4,6 +4,8 @@ import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
 import type { DefineComponent } from 'vue';
 import { createSSRApp, h } from 'vue';
 import { renderToString } from 'vue/server-renderer';
+import { createLocalization } from '@/lib/localization';
+import type { LocalizationSettings } from '@/types/localization';
 
 const appName = import.meta.env.VITE_APP_NAME || 'Laravel';
 
@@ -19,7 +21,14 @@ createServer(
                     import.meta.glob<DefineComponent>('./pages/**/*.vue'),
                 ),
             setup: ({ App, props, plugin }) =>
-                createSSRApp({ render: () => h(App, props) }).use(plugin),
+                createSSRApp({ render: () => h(App, props) })
+                    .use(plugin)
+                    .use(
+                        createLocalization(
+                            props.initialPage.props
+                                .localization as LocalizationSettings,
+                        ),
+                    ),
         }),
     { cluster: true },
 );

resources/js/types/global.d.ts

@@ -1,4 +1,5 @@
 import type { Auth } from '@/types/auth';
+import type { LocalizationSettings } from '@/types/localization';
 import type { Page, Router } from '@inertiajs/core';
 import { createHeadManager } from '@inertiajs/vue3';
 
@@ -19,6 +20,7 @@ declare module '@inertiajs/core' {
     export interface InertiaConfig {
         sharedPageProps: {
             name: string;
+            localization: LocalizationSettings;
             auth: Auth;
             sidebarOpen: boolean;
         };

resources/js/types/localization.ts

@@ -0,0 +1,13 @@
+import type { en } from '@/locales/en';
+
+export type TranslationKey = keyof typeof en;
+export type PluralMessage = Partial<Record<Intl.LDMLPluralRule, string>> & {
+    other: string;
+};
+export type TranslationCatalog = Record<TranslationKey, string | PluralMessage>;
+export type TranslationParameters = Record<string, string | number>;
+
+export type LocalizationSettings = {
+    locale: string;
+    timeZone: string;
+};