refactor: Localization

BREAKING CHANGE: Removed `getLocale` and `Locale`

- Rename `Locale` to `L10nEngine`
- Rename `Locale.getLocaleStr` to `Locale.getTemplate`
- Rename `getLocale` to `createL10n`

Author: abichinger

core/src/__tests__/locale.spec.ts

@@ -1,9 +1,9 @@
-import { getLocale } from '@/locale'
+import { createL10n } from '@/locale'
 import { FieldPattern, TextPosition } from '@/types'
 import { describe, expect, it } from 'vitest'
 
 describe('locale', () => {
-  it('getLocale', () => {
+  it('createL10n', () => {
     const testCases = [
       { locale: 'en', expected: 'Hour' },
       { locale: 'foo-bar', expected: 'Hour' },
@@ -13,43 +13,43 @@ describe('locale', () => {
     ]
 
     for (const test of testCases) {
-      const l = getLocale(test.locale)
-      expect(l.getLocaleStr('hour', 'text')).toBe(test.expected)
+      const l = createL10n(test.locale)
+      expect(l.getTemplate('hour', 'text')).toBe(test.expected)
     }
   })
 
-  it('getLocaleStr', () => {
-    const l = getLocale('en', {
+  it('getTemplate', () => {
+    const l = createL10n('en', {
       custom: {
         '*': 'bar',
         message: 'baz',
       },
     })
 
-    expect(l.getLocaleStr('year', 'minute', 'empty', 'text')).toBe('every {{field.id}}')
-    expect(l.getLocaleStr('year', 'dayOfWeek', 'value', 'prefix')).toBe('and')
-    expect(l.getLocaleStr('year', 'minute', 'range', 'prefix')).toBe(':')
-    expect(l.getLocaleStr('custom', 'foo')).toBe('bar')
-    expect(l.getLocaleStr('custom', 'message')).toBe('baz')
+    expect(l.getTemplate('year', 'minute', 'any', 'text')).toBe('every {{field.id}}')
+    expect(l.getTemplate('year', 'dayOfWeek', 'value', 'prefix')).toBe('and')
+    expect(l.getTemplate('year', 'minute', 'range', 'prefix')).toBe(':')
+    expect(l.getTemplate('custom', 'foo')).toBe('bar')
+    expect(l.getTemplate('custom', 'message')).toBe('baz')
   })
 
-  it('getLocaleStr pt', () => {
-    const l = getLocale('pt', {
+  it('getTemplate pt', () => {
+    const l = createL10n('pt', {
       custom: {
         '*': 'bar',
         message: 'baz',
       },
     })
 
-    expect(l.getLocaleStr('year', 'minute', 'empty', 'text')).toBe('cada minuto')
-    expect(l.getLocaleStr('year', 'dayOfWeek', 'value', 'prefix')).toBe('e de')
-    expect(l.getLocaleStr('year', 'minute', 'range', 'prefix')).toBe(':')
-    expect(l.getLocaleStr('custom', 'foo')).toBe('bar')
-    expect(l.getLocaleStr('custom', 'message')).toBe('baz')
+    expect(l.getTemplate('year', 'minute', 'any', 'text')).toBe('cada minuto')
+    expect(l.getTemplate('year', 'dayOfWeek', 'value', 'prefix')).toBe('e de')
+    expect(l.getTemplate('year', 'minute', 'range', 'prefix')).toBe(':')
+    expect(l.getTemplate('custom', 'foo')).toBe('bar')
+    expect(l.getTemplate('custom', 'message')).toBe('baz')
   })
 
   it('render', () => {
-    const l = getLocale('en', {
+    const l = createL10n('en', {
       '*': {
         '*': {
           value: {

core/src/components/__tests__/cron-segment.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { getLocale } from '@/locale'
+import { createL10n } from '@/locale'
 import { FieldWrapper } from '@/types'
 import { defaultItems } from '@/util'
 import { nextTick, ref } from 'vue'
@@ -15,7 +15,7 @@ const f = () => {
   const period = { id: 'year', value: [] }
 
   return useCronSegment({
-    locale: getLocale('en'),
+    l10n: createL10n('en'),
     field: fieldDesc,
     period: ref(period),
     initialCron: '*',

core/src/components/cron-core.ts

@@ -1,4 +1,5 @@
 import { AnySegment, NoSpecificSegment, RangeSegment, StepSegment, ValueSegment } from '@/cron'
+import { createL10n } from '@/locale'
 import type { Localization } from '@/locale/types'
 import {
   computed,
@@ -9,7 +10,6 @@ import {
   type PropType,
   type SetupContext,
 } from 'vue'
-import { getLocale } from '../locale'
 import { FieldWrapper, TextPosition, type CronFormat, type Field, type Period } from '../types'
 import { defaultItems } from '../util'
 import { useCronSegment, type UseCronSegmentReturn } from './cron-segment'
@@ -142,11 +142,11 @@ export function useCron(options: CronOptions) {
   const { customLocale, fields = cronDefaults.fields(format, locale) } = options
   const initialValue = options.initialValue ?? cronDefaults.initialValue(fields.length)
 
-  const l10n = getLocale(locale, customLocale)
+  const l10n = createL10n(locale, customLocale)
   const periods = (options.periods ?? cronDefaults.periods(format)).map((p) => {
     return {
       ...p,
-      text: p.text ?? l10n.getLocaleStr(p.id, TextPosition.Text),
+      text: p.text ?? l10n.getTemplate(p.id, TextPosition.Text),
     }
   })
   const initialPeriod =
@@ -160,7 +160,7 @@ export function useCron(options: CronOptions) {
   const periodPrefix = ref('')
   const periodSuffix = ref('')
   const segments = fields.map((f) => {
-    return useCronSegment({ field: new FieldWrapper(f), locale: l10n, period })
+    return useCronSegment({ field: new FieldWrapper(f), l10n, period })
   })
 
   const segmentMap = new Map(segments.map((s) => [s.id, s]))
@@ -205,8 +205,8 @@ export function useCron(options: CronOptions) {
   }
 
   const translate = () => {
-    periodPrefix.value = l10n.getLocaleStr(period.value.id, TextPosition.Prefix)
-    periodSuffix.value = l10n.getLocaleStr(period.value.id, TextPosition.Suffix)
+    periodPrefix.value = l10n.getTemplate(period.value.id, TextPosition.Prefix)
+    periodSuffix.value = l10n.getTemplate(period.value.id, TextPosition.Suffix)
   }
   translate()
 

core/src/components/cron-segment.ts

@@ -1,17 +1,17 @@
 import { CombinedSegment, arrayToSegment, cronToSegment } from '@/cron'
-import type { Locale } from '@/locale'
+import type { L10nEngine } from '@/locale'
 import { TextPosition, type CronSegment, type FieldWrapper, type Period } from '@/types'
 import { ref, watch, type Ref } from 'vue'
 
 export interface FieldOptions {
-  locale: Locale
+  l10n: L10nEngine
   period: Ref<Period>
   field: FieldWrapper
   initialCron?: string
 }
 
 export function useCronSegment(options: FieldOptions) {
-  const { period, field, initialCron = '*', locale } = options
+  const { period, field, initialCron = '*', l10n } = options
 
   const cron = ref(initialCron)
   const error = ref('')
@@ -26,15 +26,15 @@ export function useCronSegment(options: FieldOptions) {
 
     text.value = segments
       .map((seg) => {
-        return locale.render(period.value.id, field.id, seg.type, TextPosition.Text, {
+        return l10n.render(period.value.id, field.id, seg.type, TextPosition.Text, {
           field: field,
           ...seg.items,
         })
       })
       .join(',')
 
-    prefix.value = locale.getLocaleStr(period.value.id, field.id, seg.type, TextPosition.Prefix)
-    suffix.value = locale.getLocaleStr(period.value.id, field.id, seg.type, TextPosition.Suffix)
+    prefix.value = l10n.getTemplate(period.value.id, field.id, seg.type, TextPosition.Prefix)
+    suffix.value = l10n.getTemplate(period.value.id, field.id, seg.type, TextPosition.Suffix)
   }
 
   const parseCron = (cron: string) => {

core/src/index.ts

@@ -19,7 +19,7 @@ export {
   type SelectOptions,
   type UseSelectReturn,
 } from './components/select'
-export { Locale, getLocale } from './locale'
+export { createL10n, L10nEngine } from './locale'
 export type * from './locale/types'
 export type * from './types'
 export { FieldPattern, FieldWrapper, TextPosition } from './types'

core/src/locale/index.ts

@@ -31,45 +31,59 @@ const locales: Record<string, Localization> = {
   ko,
 }
 
-class Locale {
+class L10nEngine {
   dict: Localization
 
   constructor(dict: Localization) {
     this.dict = dict
   }
 
-  getLocaleStr(...keys: string[]) {
+  /**
+   * Gets a localization template by traversing the dictionary using provided keys.
+   * @param keys - Array of keys to traverse through the localization dictionary
+   * @returns The found template string or empty string if not found
+   */
+  getTemplate(...keys: string[]) {
     const k = keys.map((key) => [key, '*'])
     return traverse(this.dict, ...k) || ''
   }
 
+  /**
+   * Renders a localization template with the provided parameters using Mustache.
+   * @param periodId - The period identifier (e.g. 'year', 'month')
+   * @param fieldId - The field identifier (e.g. 'hour', 'minute')
+   * @param fieldPattern - The pattern type of the field
+   * @param position - The text position
+   * @param params - Parameters to be interpolated into the template
+   * @returns The rendered localization string
+   */
   render(
     periodId: string,
     fieldId: string,
     fieldPattern: FieldPattern,
     position: TextPosition,
     params: any,
   ) {
-    const template = this.getLocaleStr(periodId, fieldId, fieldPattern, position)
+    const template = this.getTemplate(periodId, fieldId, fieldPattern, position)
     return Mustache.render(template, params || {})
   }
 }
 
 /**
- *
- * @param locale - locale code, e.g.: en, en-GB de-DE
- * @param mixin - can be used to override values of the Locale
- * @returns {Locale} Dictionary with all strings in the requested language
+ * Creates a localization engine for the specified locale.
+ * @param localeCode - Locale code (e.g. 'en', 'en-GB', 'de-DE')
+ * @param mixin - Optional dictionary to override default locale strings
+ * @returns A new L10nEngine instance for the specified locale with English as fallback
  */
-function getLocale(localeCode: string, mixin?: Localization) {
+function createL10n(localeCode: string, mixin?: Localization) {
   const [language] = localeCode.split('-')
   const l = locales[localeCode.toLowerCase()] || locales[language.toLowerCase()] || locales.en
   // Note: always use an empty object as target
   const dict = deepMerge({}, locales.en, l, mixin || {}) as Localization
-  return new Locale(dict)
+  return new L10nEngine(dict)
 }
 
-export { getLocale, Locale }
+export { createL10n, L10nEngine }
 
 // The following prompt was used for localizations translated with GPT-4:
 //