@userfrosting/sprinkle-core 6.0.0-alpha.2 → 6.0.0-alpha.3

package/app/assets/composables/usePageMeta.ts

@@ -1,5 +1,6 @@
 import { computed, ref, watch } from 'vue'
 import { useRoute } from 'vue-router'
+import { useTranslator } from '@userfrosting/sprinkle-core/stores'
 import { useConfigStore } from '../stores'
 import { defineStore } from 'pinia'
 
@@ -17,6 +18,7 @@ export const usePageMeta = defineStore('pageMeta', () => {
      * Globally provided properties
      */
     const route = useRoute()
+    const { translate } = useTranslator()
 
     /**
      * States
@@ -68,7 +70,7 @@ export const usePageMeta = defineStore('pageMeta', () => {
 
         // Update Page Title & Description with current route
         title.value = route.meta.title || ''
-        description.value = route.meta.description || ''
+        description.value = translate(route.meta.description || '')
     }
 
     // Update the document title
@@ -90,7 +92,7 @@ export const usePageMeta = defineStore('pageMeta', () => {
      */
     const siteTitle = computed<string>(() => useConfigStore().get('site.title') || '')
     const pageFullTitle = computed<string>(() => {
-        return title.value ? title.value + ' | ' + siteTitle.value : siteTitle.value
+        return title.value ? translate(title.value) + ' | ' + siteTitle.value : siteTitle.value
     })
 
     /**

package/app/assets/index.d.ts

@@ -0,0 +1,9 @@
+export {}
+
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        // TODO : Use interface from sprinkle-core
+        $t: (key: string, placeholders?: string | number | object) => string
+        $tdate: (date: string, format?: string | object) => string
+    }
+}

package/app/assets/index.ts

@@ -1,8 +1,19 @@
-import { useConfigStore } from './stores'
+import type { App } from 'vue'
+import { useConfigStore, useTranslator } from './stores'
 
+/**
+ * Core Sprinkle initialization recipe.
+ *
+ * This recipe is responsible for loading the configuration from the api.
+ */
 export default {
-    install: () => {
-        const config = useConfigStore()
-        config.load()
+    install: (app: App) => {
+        useConfigStore().load()
+
+        // Load translations & add $t to global properties
+        const { translate, translateDate, load } = useTranslator()
+        load()
+        app.config.globalProperties.$t = translate
+        app.config.globalProperties.$tdate = translateDate
     }
 }

package/app/assets/interfaces/DictionaryApi.ts

@@ -0,0 +1,25 @@
+/**
+ * Api Interface - What the API expects and what it returns
+ *
+ * This interface is tied to the `DictionaryController` API, accessed at the
+ * GET `/api/dictionary` endpoint.
+ *
+ * This api doesn't have a corresponding Request data interface.
+ */
+export interface DictionaryResponse {
+    identifier: string
+    config: DictionaryConfig
+    dictionary: DictionaryEntries
+}
+
+export interface DictionaryEntries {
+    [key: string]: string
+}
+
+export interface DictionaryConfig {
+    name: string
+    regional: string
+    authors: string[]
+    plural_rule: number
+    dates: string
+}

package/app/assets/interfaces/index.ts

@@ -24,6 +24,7 @@ export type { AssociativeArray } from './common'
 export { Severity } from './severity'
 export type { Sprunjer, SprunjerData, SprunjerListable, SprunjerListableOption } from './sprunjer'
 export type { SprunjerRequest, SprunjerResponse } from './sprunjerApi'
+export type { DictionaryResponse, DictionaryEntries, DictionaryConfig } from './DictionaryApi'
 
 // Misc
 export type { ApiResponse } from './ApiResponse'

package/app/assets/stores/Helpers/PluralRules.ts

@@ -0,0 +1,218 @@
+/**
+ * Families: Asian (Chinese, Japanese, Korean, Vietnamese), Persian, Turkic/Altaic (Turkish), Thai, Lao
+ * 1 - everything: 0, 1, 2, ...
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export const rule0 = (number: number): number => {
+    return 1
+}
+
+/**
+ * Families: Germanic (Danish, Dutch, English, Faroese, Frisian, German, Norwegian, Swedish),
+ * Finno-Ugric (Estonian, Finnish, Hungarian), Language isolate (Basque),
+ * Latin/Greek (Greek), Semitic (Hebrew), Romanic (Italian, Portuguese, Spanish, Catalan)
+ * 1 - 1
+ * 2 - everything else: 0, 2, 3, ...
+ */
+export const rule1 = (number: number): number => {
+    return number === 1 ? 1 : 2
+}
+
+/**
+ * Families: Romanic (French, Brazilian Portuguese)
+ * 1 - 0, 1
+ * 2 - everything else: 2, 3, ...
+ */
+export const rule2 = (number: number): number => {
+    return number === 0 || number === 1 ? 1 : 2
+}
+
+/**
+ * Families: Baltic (Latvian)
+ * 1 - 0
+ * 2 - ends in 1, not 11: 1, 21, ... 101, 121, ...
+ * 3 - everything else: 2, 3, ... 10, 11, 12, ... 20, 22, ...
+ */
+export const rule3 = (number: number): number => {
+    return number === 0 ? 1 : number % 10 == 1 && number % 100 != 11 ? 2 : 3
+}
+
+/**
+ * Families: Celtic (Scottish Gaelic)
+ * 1 - is 1 or 11: 1, 11
+ * 2 - is 2 or 12: 2, 12
+ * 3 - others between 3 and 19: 3, 4, ... 10, 13, ... 18, 19
+ * 4 - everything else: 0, 20, 21, ...
+ */
+export const rule4 = (number: number): number => {
+    return number === 1 || number == 11
+        ? 1
+        : number === 2 || number === 12
+          ? 2
+          : number >= 3 && number <= 19
+            ? 3
+            : 4
+}
+
+/**
+ * Families: Romanic (Romanian)
+ * 1 - 1
+ * 2 - is 0 or ends in 01-19: 0, 2, 3, ... 19, 101, 102, ... 119, 201, ...
+ * 3 - everything else: 20, 21, ...
+ */
+export const rule5 = (number: number): number => {
+    return number === 1 ? 1 : number === 0 || (number % 100 > 0 && number % 100 < 20) ? 2 : 3
+}
+
+/**
+ * Families: Baltic (Lithuanian)
+ * 1 - ends in 1, not 11: 1, 21, 31, ... 101, 121, ...
+ * 2 - ends in 0 or ends in 10-20: 0, 10, 11, 12, ... 19, 20, 30, 40, ...
+ * 3 - everything else: 2, 3, ... 8, 9, 22, 23, ... 29, 32, 33, ...
+ */
+export const rule6 = (number: number): number => {
+    return number % 10 === 1 && number % 100 !== 11
+        ? 1
+        : number % 10 < 2 || (number % 100 >= 10 && number % 100 < 20)
+          ? 2
+          : 3
+}
+
+/**
+ * Families: Slavic (Croatian, Serbian, Russian, Ukrainian)
+ * 1 - ends in 1, not 11: 1, 21, 31, ... 101, 121, ...
+ * 2 - ends in 2-4, not 12-14: 2, 3, 4, 22, 23, 24, 32, ...
+ * 3 - everything else: 0, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 25, 26, ...
+ */
+export const rule7 = (number: number): number => {
+    return number % 10 === 1 && number % 100 !== 11
+        ? 1
+        : number % 10 >= 2 && number % 10 <= 4 && (number % 100 < 10 || number % 100 >= 20)
+          ? 2
+          : 3
+}
+
+/**
+ * Families: Slavic (Slovak, Czech)
+ * 1 - 1
+ * 2 - 2, 3, 4
+ * 3 - everything else: 0, 5, 6, 7, ...
+ */
+export const rule8 = (number: number): number => {
+    return number === 1 ? 1 : number >= 2 && number <= 4 ? 2 : 3
+}
+
+/**
+ * Families: Slavic (Polish)
+ * 1 - 1
+ * 2 - ends in 2-4, not 12-14: 2, 3, 4, 22, 23, 24, 32, ... 104, 122, ...
+ * 3 - everything else: 0, 5, 6, ... 11, 12, 13, 14, 15, ... 20, 21, 25, ...
+ */
+export const rule9 = (number: number): number => {
+    return number === 1
+        ? 1
+        : number % 10 >= 2 && number % 10 <= 4 && (number % 100 < 12 || number % 100 > 14)
+          ? 2
+          : 3
+}
+
+/**
+ * Families: Slavic (Slovenian, Sorbian)
+ * 1 - ends in 01: 1, 101, 201, ...
+ * 2 - ends in 02: 2, 102, 202, ...
+ * 3 - ends in 03-04: 3, 4, 103, 104, 203, 204, ...
+ * 4 - everything else: 0, 5, 6, 7, 8, 9, 10, 11, ...
+ */
+export const rule10 = (number: number): number => {
+    return number % 100 === 1
+        ? 1
+        : number % 100 === 2
+          ? 2
+          : number % 100 === 3 || number % 100 === 4
+            ? 3
+            : 4
+}
+
+/**
+ * Families: Celtic (Irish Gaeilge)
+ * 1 - 1
+ * 2 - 2
+ * 3 - is 3-6: 3, 4, 5, 6
+ * 4 - is 7-10: 7, 8, 9, 10
+ * 5 - everything else: 0, 11, 12, ...
+ */
+export const rule11 = (number: number): number => {
+    return number === 1
+        ? 1
+        : number === 2
+          ? 2
+          : number >= 3 && number <= 6
+            ? 3
+            : number >= 7 && number <= 10
+              ? 4
+              : 5
+}
+
+/**
+ * Families: Semitic (Arabic).
+ *
+ * 1 - 1
+ * 2 - 2
+ * 3 - ends in 03-10: 3, 4, ... 10, 103, 104, ... 110, 203, 204, ...
+ * 4 - ends in 11-99: 11, ... 99, 111, 112, ...
+ * 5 - everything else: 100, 101, 102, 200, 201, 202, ...
+ * 6 - 0
+ */
+export const rule12 = (number: number): number => {
+    return number === 1
+        ? 1
+        : number === 2
+          ? 2
+          : number % 100 >= 3 && number % 100 <= 10
+            ? 3
+            : number % 100 >= 11
+              ? 4
+              : number != 0
+                ? 5
+                : 6
+}
+
+/**
+ * Families: Semitic (Maltese)
+ * 1 - 1
+ * 2 - is 0 or ends in 01-10: 0, 2, 3, ... 9, 10, 101, 102, ...
+ * 3 - ends in 11-19: 11, 12, ... 18, 19, 111, 112, ...
+ * 4 - everything else: 20, 21, ...
+ */
+export const rule13 = (number: number): number => {
+    return number === 1
+        ? 1
+        : number === 0 || (number % 100 >= 1 && number % 100 < 11)
+          ? 2
+          : number % 100 > 10 && number % 100 < 20
+            ? 3
+            : 4
+}
+
+/**
+ * Families: Slavic (Macedonian)
+ * 1 - ends in 1: 1, 11, 21, ...
+ * 2 - ends in 2: 2, 12, 22, ...
+ * 3 - everything else: 0, 3, 4, ... 10, 13, 14, ... 20, 23, ...
+ */
+export const rule14 = (number: number): number => {
+    return number % 10 === 1 ? 1 : number % 10 === 2 ? 2 : 3
+}
+
+/**
+ * Families: Icelandic
+ * 1 - ends in 1, not 11: 1, 21, 31, ... 101, 121, 131, ...
+ * 2 - everything else: 0, 2, 3, ... 10, 11, 12, ... 20, 22, ...
+ */
+export const rule15 = (number: number): number => {
+    return number % 10 === 1 && number % 100 != 11 ? 1 : 2
+}
+
+export interface PluralRules {
+    [key: number]: (pluralValue: number) => number
+}

package/app/assets/stores/index.ts

@@ -1 +1,2 @@
 export { useConfigStore } from './config'
+export { useTranslator } from './useTranslator'

package/app/assets/stores/useTranslator.ts

@@ -0,0 +1,293 @@
+/**
+ * Translator composable store.
+ *
+ * This pinia store is used to access the translator and to use the translator.
+ */
+import { ref } from 'vue'
+import { defineStore } from 'pinia'
+import axios from 'axios'
+import type { DictionaryEntries, DictionaryResponse, DictionaryConfig } from '../interfaces'
+import { DateTime } from 'luxon'
+import type { PluralRules } from './Helpers/PluralRules'
+import {
+    rule0,
+    rule1,
+    rule2,
+    rule3,
+    rule4,
+    rule5,
+    rule6,
+    rule7,
+    rule8,
+    rule9,
+    rule10,
+    rule11,
+    rule12,
+    rule13,
+    rule14,
+    rule15
+} from './Helpers/PluralRules'
+
+// List all available plural rules
+const rules: PluralRules = {
+    0: rule0,
+    1: rule1,
+    2: rule2,
+    3: rule3,
+    4: rule4,
+    5: rule5,
+    6: rule6,
+    7: rule7,
+    8: rule8,
+    9: rule9,
+    10: rule10,
+    11: rule11,
+    12: rule12,
+    13: rule13,
+    14: rule14,
+    15: rule15
+}
+
+export const useTranslator = defineStore(
+    'translator',
+    () => {
+        /**
+         * Variables
+         */
+        const defaultPluralKey = 'plural'
+        const identifier = ref<string>('')
+        const dictionary = ref<DictionaryEntries>({})
+        const config = ref<DictionaryConfig>({
+            name: '',
+            regional: '',
+            authors: [],
+            plural_rule: 0,
+            dates: ''
+        })
+
+        /**
+         * Functions
+         */
+        // Load the dictionary from the API
+        async function load() {
+            axios.get<DictionaryResponse>('/api/dictionary').then((response) => {
+                identifier.value = response.data.identifier
+                config.value = response.data.config
+                dictionary.value = response.data.dictionary
+            })
+        }
+
+        // The translate function
+        function translate(key: string, placeholders: string | number | object = {}): string {
+            const { message, placeholders: mutatedPlaceholders } = getMessageFromKey(
+                key,
+                placeholders
+            )
+            placeholders = mutatedPlaceholders
+
+            return replacePlaceholders(message, placeholders)
+        }
+
+        /**
+         * Format a date to the user locale
+         *
+         * @param date The date to format, in ISO format
+         * @param format The format to use. Default to `DATETIME_MED_WITH_WEEKDAY`.
+         *               See the Luxon documentation for more information on formatting
+         *
+         * @see https://moment.github.io/luxon/#/formatting?id=presets
+         * @see https://moment.github.io/luxon/#/formatting?id=table-of-tokens
+         */
+        function translateDate(
+            date: string,
+            format: string | object = DateTime.DATETIME_MED_WITH_WEEKDAY
+        ): string {
+            const dt = getDateTime(date)
+            if (typeof format === 'object') {
+                return dt.toLocaleString(format)
+            } else {
+                return dt.toFormat(format)
+            }
+        }
+
+        /**
+         * Returns the Luxon DateTime object for the given date, with the user
+         * locale, so Luxon methods can be used without having to set the locale
+         *
+         * @param date The date to format, in ISO format
+         */
+        function getDateTime(date: string): DateTime {
+            return DateTime.fromISO(date).setLocale(config.value.dates)
+        }
+
+        // TODO : Add doc + make Placeholders a type
+        function getMessageFromKey(
+            key: string,
+            placeholders: string | number | Record<string, any>
+        ): { message: string; placeholders: string | number | Record<string, any> } {
+            // Return direct match
+            if (dictionary.value[key] !== undefined) {
+                return { message: dictionary.value[key], placeholders }
+            }
+
+            // First, let's see if we can get the plural rules.
+            // A plural form will always have priority over the `@TRANSLATION` instruction
+            // We start by picking up the plural key, aka which placeholder contains the numeric value defining how many {x} we have
+            const pluralKey = dictionary.value[key + '.@PLURAL'] || defaultPluralKey
+
+            // Let's get the plural value, aka how many {x} we have
+            // If no plural value was found, we fallback to `@TRANSLATION` instruction or default to 1 as a last resort
+            let pluralValue: number = 1
+            if (typeof placeholders === 'object' && placeholders[pluralKey] !== undefined) {
+                pluralValue = Number(placeholders[pluralKey])
+            } else if (typeof placeholders === 'number' || typeof placeholders === 'string') {
+                pluralValue = Number(placeholders)
+            } else if (dictionary.value[key + '.@TRANSLATION'] !== undefined) {
+                // We have a `@TRANSLATION` instruction, return this
+                return { message: dictionary.value[key + '.@TRANSLATION'], placeholders }
+            }
+
+            // If placeholders is a numeric value, we transform back to an array for replacement in the main message
+            if (typeof placeholders === 'number' || typeof placeholders === 'string') {
+                placeholders = { [pluralKey]: pluralValue }
+            } else if (typeof placeholders === 'object' && placeholders[pluralKey] === undefined) {
+                placeholders = { ...placeholders, [pluralKey]: pluralValue }
+            }
+
+            // At this point, we need to go deeper and find the correct plural form to use
+            const pluralRuleKey = getPluralMessageKey(key, pluralValue)
+
+            // Only return if the plural is not null. Will happen if the message array don't follow the rules
+            if (dictionary.value[key + '.' + pluralRuleKey] !== undefined) {
+                return { message: dictionary.value[key + '.' + pluralRuleKey], placeholders }
+            }
+
+            // One last check... If we don't have a rule, but the $pluralValue
+            // as a key does exist, we might still be able to return it
+            if (dictionary.value[key + '.' + pluralValue] !== undefined) {
+                return { message: dictionary.value[key + '.' + pluralValue], placeholders }
+            }
+
+            // Return @TRANSLATION match
+            if (dictionary.value[key + '.@TRANSLATION'] !== undefined) {
+                return { message: dictionary.value[key + '.@TRANSLATION'], placeholders }
+            }
+
+            // If the message is an array, but we can't find a plural form or a "@TRANSLATION" instruction, we can't go further.
+            // We can't return the array, so we'll return the key
+            return { message: key, placeholders }
+        }
+
+        function replacePlaceholders(
+            message: string,
+            placeholders: string | number | Record<string, any>
+        ): string {
+            // If placeholders is not an object at this point, we make it an object, using `plural` as the key
+            if (typeof placeholders !== 'object') {
+                placeholders = { [defaultPluralKey]: placeholders }
+            }
+
+            // Interpolate translatable placeholders values. This allows to
+            // pre-translate placeholder which value starts with the `&` character
+            // console.debug('Looping Placeholders', placeholders)
+            for (const [name, value] of Object.entries(placeholders)) {
+                // console.debug(`> ${name}: ${value}`)
+
+                //We don't allow nested placeholders. They will return errors on the next lines
+                if (typeof value !== 'string') {
+                    continue
+                }
+
+                // We test if the placeholder value starts the "&" character.
+                // That means we need to translate that placeholder value
+                if (value.startsWith('&')) {
+                    // Remove the current placeholder from the master $placeholder
+                    // array, otherwise we end up in an infinite loop
+                    const data = Object.fromEntries(
+                        Object.entries(placeholders).filter(([k]) => k !== name)
+                    )
+
+                    // Translate placeholders value and place it in the main $placeholder array
+                    placeholders[name] = translate(value.substring(1), data)
+                }
+            }
+
+            // We check for {{&...}} strings in the resulting message.
+            // While the previous loop pre-translated placeholder value, this one
+            // pre-translate the message string vars
+            // We use some regex magic to detect them !
+            message = message.replace(/{{&(([^}]+[^a-z]))}}/g, (match, p1) => {
+                return translate(p1, placeholders)
+            })
+
+            // Now it's time to replace the remaining placeholder.
+            for (const [name, value] of Object.entries(placeholders)) {
+                const regex = new RegExp(`{{${name}}}`, 'g')
+                message = message.replace(regex, String(value))
+            }
+
+            return message
+        }
+
+        /**
+         * Return the correct plural message form to use.
+         * When multiple plural form are available for a message, this method will return the correct oen to use based on the numeric value.
+         *
+         * @param int     $pluralValue  The numeric value used to select the correct message
+         *
+         * @return int|null Returns which key from $messageArray to use
+         */
+        function getPluralMessageKey(key: string, pluralValue: number): number | null {
+            // Bypass the rules for a value of "0". Instead of returning the
+            // correct plural form (>= 1), we force return the "0" form, which
+            // can used to display "0 users" as "No users".
+            if (pluralValue === 0 && dictionary.value[key + '.0'] !== undefined) {
+                return 0
+            }
+
+            // Get the correct plural form to use depending on the language
+            const pluralForm = getPluralForm(pluralValue)
+
+            // If the dictionary contains a string for this form, return the form
+            if (dictionary.value[key + '.' + pluralForm] !== undefined) {
+                return pluralForm
+            }
+
+            // If the key we need doesn't exist, use the previous available one, including the special "0" form
+            // This is a fallback to avoid errors when the dictionary is not complete
+            for (let i = pluralForm; i >= 0; i--) {
+                if (dictionary.value[key + '.' + i] !== undefined) {
+                    return i
+                }
+            }
+
+            // If no key was found, null will be returned
+            return null
+        }
+
+        function getPluralForm(pluralValue: number, forceRule?: number): number {
+            const rule = forceRule ?? config.value.plural_rule
+
+            if (rule < 0 || rule >= Object.keys(rules).length) {
+                throw new Error(`The rule number ${rule} must be between 0 and 15`)
+            }
+
+            return rules[rule](pluralValue)
+        }
+
+        /**
+         * Return store
+         */
+        return {
+            dictionary,
+            load,
+            config,
+            identifier,
+            translate,
+            translateDate,
+            getPluralForm,
+            getDateTime
+        }
+    },
+    { persist: true }
+)

package/app/assets/tests/plugin.test.ts

@@ -1,17 +1,26 @@
 import { describe, expect, test, vi } from 'vitest'
+import { createApp } from 'vue'
 import { useConfigStore } from '../stores/config'
 import plugin from '..'
 import * as Config from '../stores/config'
+import * as Translator from '../stores/useTranslator'
 
 const mockConfigStore = {
     load: vi.fn()
 }
 
+const mockTranslatorStore = {
+    load: vi.fn()
+}
+
 describe('Plugin', () => {
     test('should install the plugin and initiate load', () => {
+        const app = createApp({})
+
         vi.spyOn(Config, 'useConfigStore').mockReturnValue(mockConfigStore as any)
+        vi.spyOn(Translator, 'useTranslator').mockReturnValue(mockTranslatorStore as any)
 
-        plugin.install()
+        plugin.install(app)
 
         expect(useConfigStore).toHaveBeenCalled()
         expect(mockConfigStore.load).toHaveBeenCalled()