@kosdev-code/kos-ui-sdk 0.1.0-dev.5053

package/models/models/translation/services/translation-services.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Translation service functions for internationalization and localization.
+ *
+ * This module provides service functions for loading translation data, managing locale
+ * descriptors, and handling multi-language content in KOS applications. Supports both
+ * static file-based translations and dynamic translation service integration.
+ *
+ * @module TranslationServices
+ */
+/**
+ * Generic translation data response format.
+ *
+ * Represents the structure of translation data returned from various translation
+ * endpoints, supporting flexible key-value structures for different locales
+ * and translation namespaces.
+ *
+ * @group KOS Model
+ * @category i18n
+ */
+export type TranslationResponse = Record<string, any>;
+/**
+ * Locale descriptor defining translation file location and fallback behavior.
+ *
+ * Describes how to locate and load translation files for a specific locale,
+ * including fallback chains for graceful degradation when translations are
+ * missing or incomplete.
+ *
+ * @group KOS Model
+ * @category i18n
+ */
+export interface LocaleDescriptor {
+    /** Default locale to use when this locale's translations are unavailable */
+    defaultLocale: string;
+    /** Path to the translation file for this locale */
+    file: string;
+    /** Optional array of fallback locales to try in order */
+    fallbacks?: string[];
+}
+/**
+ * Complete localization configuration for organizing translation namespaces.
+ *
+ * Defines the structure for managing multiple translation namespaces with
+ * locale-specific configurations. Enables organized translation management
+ * across different features or components of an application.
+ *
+ * @group KOS Model
+ * @category i18n
+ */
+export interface Localization {
+    /**
+     * Translation namespaces organized by feature or component.
+     * Each namespace contains locale configurations and file paths.
+     */
+    namespaces: {
+        [key: string]: {
+            /** Locale-specific configuration for this namespace */
+            locales: {
+                [key: string]: LocaleDescriptor;
+            };
+            /** Base path for translation files in this namespace */
+            basePath: string;
+        };
+    };
+    /** Root path for the localization configuration */
+    path: string;
+}
+/**
+ * Loads translation data from a specified URL.
+ *
+ * Fetches translation JSON files from static resources or translation services.
+ * Handles network errors gracefully by returning empty objects rather than
+ * throwing exceptions, enabling fallback behavior in translation systems.
+ *
+ * @param url - Relative or absolute URL to the translation file
+ * @param root - Optional root URL override (defaults to current window origin)
+ * @returns Promise resolving to translation data object
+ *
+ * @throws {Error} When network request fails unexpectedly (non-200 responses return empty object)
+ *
+ * @example Load Translation File
+ * ```typescript
+ * const frenchTranslations = await getTranslations('/assets/locales/fr/common.json');
+ * console.log('Welcome message:', frenchTranslations.welcome);
+ *
+ * const customTranslations = await getTranslations('/api/translations/dashboard', 'https://translations.example.com');
+ * ```
+ *
+ * @group KOS Model
+ * @category i18n
+ */
+export declare const getTranslations: (url: string, root?: string) => Promise<any>;
+/**
+ * Retrieves the system-wide localization configuration descriptor.
+ *
+ * Fetches the complete localization configuration from the KOS system,
+ * including namespace definitions, locale mappings, and file path information.
+ * Used for initializing translation containers with proper configuration.
+ *
+ * @returns Promise resolving to complete localization descriptor
+ *
+ * @throws {Error} When service request fails or returns non-200 status
+ *
+ * @example Initialize Translation System
+ * ```typescript
+ * const localizationConfig = await getLocalizationDescriptor();
+ * const translationContainer = TranslationContainer.instance('app-i18n')
+ *   .options({
+ *     lang: 'en',
+ *     descriptor: localizationConfig
+ *   })
+ *   .build();
+ * ```
+ *
+ * @group KOS Model
+ * @category i18n
+ */
+export declare const getLocalizationDescriptor: () => Promise<Localization>;
+/**
+ * Creates a context-specific localization descriptor retrieval function.
+ *
+ * Returns a curried function that fetches localization configuration for a
+ * specific context from the KOS system. Useful for creating context-aware
+ * translation loaders that can be configured once and used multiple times.
+ *
+ * @param context - Context identifier for localization configuration
+ * @returns Async function that retrieves context-specific localization descriptor
+ *
+ * @throws {Error} When service request fails or context is not found
+ *
+ * @example Create Context-Specific Loader
+ * ```typescript
+ * const getStudioTranslations = getKosLocalizationDescriptor('studio');
+ * const studioConfig = await getStudioTranslations();
+ *
+ * const getDeviceTranslations = getKosLocalizationDescriptor('device');
+ * const deviceConfig = await getDeviceTranslations();
+ *
+ * // Use in translation container initialization
+ * const container = TranslationContainer.instance('context-aware')
+ *   .options({
+ *     lang: 'es',
+ *     descriptor: studioConfig
+ *   })
+ *   .build();
+ * ```
+ *
+ * @group KOS Model
+ * @category i18n
+ */
+export declare const getKosLocalizationDescriptor: (context: string) => () => Promise<Localization>;
+//# sourceMappingURL=translation-services.d.ts.map

package/models/models/translation/services/translation-services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/translation/services/translation-services.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,UAAU,EAAE;QACV,CAAC,GAAG,EAAE,MAAM,GAAG;YACb,uDAAuD;YACvD,OAAO,EAAE;gBACP,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAC;aACjC,CAAC;YACF,wDAAwD;YACxD,QAAQ,EAAE,MAAM,CAAC;SAClB,CAAC;KACH,CAAC;IACF,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAoBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,QAAe,MAAM,SAAS,MAAM,iBAgB/D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,yBAAyB,6BAYrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,4BAA4B,YAAa,MAAM,gCAY3D,CAAC"}

package/models/models/translation/translation-container-model.d.ts

@@ -0,0 +1,126 @@
+import { TranslationContainerOptions } from './types';
+import { TranslationModel } from './translation-model';
+import { Localization } from './services';
+import { PublicModelInterface } from '../../../core/types';
+import { IKosDataModel, IKosIdentifiable, IKosModelContainer, IKosModelHolder, KosCreationContext, ReloadAware } from '../../../core';
+
+export declare const MODEL_TYPE = "translation-container-model";
+/**
+ * TranslationContainer - Multi-namespace translation management with automatic locale switching.
+ *
+ * The TranslationContainer model serves as the central orchestrator for internationalization in KOS
+ * applications. It manages multiple translation namespaces, handles global locale switching, and provides
+ * namespace resolution with fallback chains. This container enables building sophisticated multi-language
+ * interfaces that adapt automatically to user language preferences across all application features.
+ *
+ * ## Key Features
+ * - **Multi-Namespace Management** - Organize translations by feature areas (dashboard, alerts, settings)
+ * - **Global Locale Control** - Centralized locale switching affects all contained translation models
+ * - **Automatic Discovery** - Dynamic namespace loading and registration as features request translations
+ * - **Fallback Resolution** - Sophisticated locale fallback chains for graceful degradation
+ * - **Custom Resolvers** - Flexible translation loading strategies for different deployment scenarios
+ * - **Reload Capability** - Dynamic translation updates without application restart
+ * - **Default Namespace** - Optional primary namespace for application-wide common translations
+ *
+ * ## Namespace Organization
+ * Translation namespaces organize translations by functional areas:
+ * - **Feature-Based**: dashboard, device-config, maintenance, alerts
+ * - **Component-Based**: forms, modals, navigation, status-displays
+ * - **Common**: common, shared, ui-elements for cross-cutting concerns
+ *
+ * ## Locale Management Architecture
+ * The container manages locale switching across all child translation models:
+ * 1. **Centralized Control**: Single point for locale changes
+ * 2. **Automatic Propagation**: All child models receive locale updates
+ * 3. **Reactive Loading**: Translation files loaded automatically on locale switch
+ * 4. **Fallback Coordination**: Container coordinates fallback chains across namespaces
+ *
+ * ## Common Use Cases
+ * - **Application Initialization** - Bootstrap internationalization system with locale descriptors
+ * - **User Language Switching** - Provide language selector that updates entire application
+ * - **Feature Translation Loading** - Dynamic namespace registration as features are accessed
+ * - **Multi-Tenant Systems** - Different translation sets for different deployments
+ * - **Development Workflows** - Hot-reload translations during development
+ * - **Global Device Interfaces** - Centralized management for device control applications
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const translationContainer = TranslationContainer.instance('app-translations')
+ *   .options({
+ *     lang: 'es',
+ *     defaultNamespace: 'common',
+ *     descriptor: {
+ *       namespaces: {
+ *         'common': {
+ *           basePath: '/assets/locales',
+ *           locales: {
+ *             'en': { file: 'en/common.json', defaultLocale: 'en' },
+ *             'es': { file: 'es/common.json', defaultLocale: 'en' }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   })
+ *   .build();
+ *
+ * // Access translations and switch language
+ * const commonTranslations = translationContainer.getModel('common');
+ * translationContainer.currentLocale = 'fr';
+ * ```
+ *
+ * @group KOS Model
+ * @category i18n
+ * @interface
+ * @useDeclaredType
+ *
+ * @see {@link TranslationContainerOptions} - Configuration options for TranslationContainer instances
+ * @see {@link TranslationModel} - Individual translation namespace model
+ * @see {@link useKosTranslation} - React hook for accessing container translations
+ * @see {@link useKosTranslationContext} - React hook for container-level operations
+ */
+export type TranslationContainerModel = PublicModelInterface<TranslationContainerModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
+export declare class TranslationContainerModelImpl implements IKosIdentifiable, IKosModelHolder<TranslationModel>, IKosDataModel, ReloadAware {
+    /** Unique identifier for the container model instance */
+    id: string;
+    /** Currently active locale for all managed translation namespaces */
+    lang: string;
+    /** Base URL for loading translation resources */
+    private rootUrl?;
+    /** Localization descriptor defining namespace configuration and locale mappings */
+    descriptor: Localization;
+    /** Optional default namespace identifier for primary application translations */
+    private _defaultNamespace?;
+    /** Path resolver function for constructing translation file URLs */
+    private resolver;
+    /** Context logger for debugging translation operations */
+    private logger;
+    /** URL for dynamically loading localization descriptors */
+    private descriptorUrl?;
+    /** Array tracking registered namespace identifiers */
+    private namespaces;
+    /** Container for managing Translation model instances */
+    private _models;
+    constructor(modelId: string, options: TranslationContainerOptions, context: KosCreationContext);
+    set currentLocale(locale: string);
+    get defaultNamespace(): TranslationModel | undefined;
+    getModel(id: string): TranslationModel | undefined;
+    get models(): IKosModelContainer<TranslationModel>;
+    get data(): TranslationModel[];
+    reload(): Promise<void>;
+    resolveNamespace(namespace: string): TranslationModel;
+    addModel(model: TranslationModel): void;
+    removeModel(id: string): void;
+    /**
+     * @internal
+     */
+    init(): Promise<void>;
+    /**
+     * @internal
+     */
+    load(): Promise<void>;
+}
+//# sourceMappingURL=translation-container-model.d.ts.map

package/models/models/translation/translation-container-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/translation/translation-container-model.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAEf,kBAAkB,EAClB,WAAW,EACZ,MAAM,eAAe,CAAC;AASvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAE3D,eAAO,MAAM,UAAU,gCAAgC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,MAAM,MAAM,yBAAyB,GACnC,oBAAoB,CAAC,6BAA6B,CAAC,CAAC;AAmBtD;;;GAGG;AACH,qBACa,6BACX,YACE,gBAAgB,EAChB,eAAe,CAAC,gBAAgB,CAAC,EACjC,aAAa,EACb,WAAW;IAEb,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,mFAAmF;IACnF,UAAU,EAAE,YAAY,CAAC;IACzB,iFAAiF;IACjF,OAAO,CAAC,iBAAiB,CAAC,CAAS;IACnC,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAIJ;IACZ,0DAA0D;IAC1D,OAAO,CAAC,MAAM,CAAmB;IACjC,2DAA2D;IAC3D,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,sDAAsD;IACtD,OAAO,CAAC,UAAU,CAAgB;IAClC,yDAAyD;IAC/C,OAAO,CAAC,OAAO,CAAuC;gBAE9D,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,2BAA2B,EACpC,OAAO,EAAE,kBAAkB;IAiB7B,IAAI,aAAa,CAAC,MAAM,EAAE,MAAM,EAK/B;IACD,IAAI,gBAAgB,iCAInB;IACD,QAAQ,CAAC,EAAE,EAAE,MAAM;IAInB,IAAI,MAAM,yCAET;IACD,IAAI,IAAI,uBAEP;IAEK,MAAM;IAMZ,gBAAgB,CAAC,SAAS,EAAE,MAAM;IA4ClC,QAAQ,CAAC,KAAK,EAAE,gBAAgB;IAIhC,WAAW,CAAC,EAAE,EAAE,MAAM;IAKtB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}

package/models/models/translation/translation-container-registration.d.ts

@@ -0,0 +1,88 @@
+import { TranslationContainerOptions } from './types';
+import { TranslationContainerModel } from './translation-container-model';
+import { SingletonKosModelRegistrationBean } from '../../../core';
+
+/**
+ * # TranslationContainer
+ *
+ * The registration bean includes convenience methods for creating and working with TranslationContainerModel instances.
+ *
+ * ## type
+ * The type property is a string that identifies the model type.
+ * The type is used to identify the model type in the model registry and to narrow down the model type in type predicates.  It's most frequently
+ * used when declaring dependencies on models.
+ *
+ * @example
+ * ```typescript
+ *
+ * @kosDependency({modelType: TranslationContainer.type, id: "translationContainerId"})
+ * private translationContainerModel: TranslationContainerModel;
+ * ```
+ *
+ *
+ * ## factory
+ *
+ * The factory method creates a factory function that can be used to create new TranslationContainerModel instances.
+ *
+ 
+ * As this is a singleton model, the factory function accepts the model options as its argument.
+ *
+ * If a model with the same model type already exists, the factory function will return the existing model.  The options will be ignored
+ * in this case and the existing model will be returned in its current state.
+ *
+ * @example
+ * ```typescript
+ * const model = TranslationContainer.factory({
+ *   // Add option data
+ * });
+ * ```
+ 
+
+ *
+ * ## predicate
+ *
+ * [Typescript type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) function that will identify and narrow down a model to a TranslationContainerModel.
+ *
+ * @example
+ * ```typescript
+ *
+ * const model: IKosDataModel = ...; // some model
+ *
+ * if (TranslationContainer.predicate(model)) {
+ *    // if the function evaluates to true, the model is narrowed down to TranslationContainerModel
+ *    // and the compiler will know that the model has the TranslationContainerModel interface
+ *    model.updateAvailability(false);
+ * }
+ * ```
+ *
+ * ## registration
+ *
+ * The registration property is an object that can be used to simplify registration of the model with the model registry.  The registration object
+ * can be spread into the model registration and provides all of the required information to register the model implementation class against the model type.
+ *
+ *
+ * @example
+ *
+ * In an application registration file you can declare the model registration as follows:
+ *
+ * **registration.ts**
+ * ```typescript
+ * import { TranslationContainer } from "@kosdev-code/kos-dispense-sdk";
+ * ...
+ * import { ExtensionManager, IKosRegistry } from "@kosdev-code/kos-ui-sdk";
+ * export const kosModels: IKosRegistry["models"] = {
+ *  ...TranslationContainer.registration,
+ * };
+ * ```
+ *
+ * ## registration.singleton
+ 
+ * The translationContainer model is a singleton model.  This means that each time the factory function is called , the same instance will be returned.
+ * If the model does not yet exist, it will be created passing in the provided options to initialize it.
+ *
+ * Singleton models don't require an ID as they will use the model type as their ID to guarantee uniqueness throughout the system.
+ * @group KOS Model
+ * @category i18n
+ * */
+export declare const TranslationContainer: Readonly<SingletonKosModelRegistrationBean<TranslationContainerModel, TranslationContainerOptions>>;
+//# sourceMappingURL=translation-container-registration.d.ts.map

package/models/models/translation/translation-container-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-container-registration.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/translation/translation-container-registration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAK/E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAiFK;AACL,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CACzC,iCAAiC,CAC/B,yBAAyB,EACzB,2BAA2B,CAC5B,CAcF,CAAC"}

package/models/models/translation/translation-context.d.ts

@@ -0,0 +1,12 @@
+import { TranslationContainerOptions } from './types';
+
+export declare const TranslationContext: {
+    set(name: string, value: any): void;
+    get(name: string): any;
+};
+export declare const KosTranslations: {
+    init(options: TranslationContainerOptions): Promise<{
+        translations: import('./translation-container-model').TranslationContainerModel;
+    }>;
+};
+//# sourceMappingURL=translation-context.d.ts.map

package/models/models/translation/translation-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-context.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/translation/translation-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAE3D,eAAO,MAAM,kBAAkB;cACnB,MAAM,SAAS,GAAG;cAMlB,MAAM;CAIjB,CAAC;AAEF,eAAO,MAAM,eAAe;kBACN,2BAA2B;;;CAKhD,CAAC"}

package/models/models/translation/translation-model.d.ts

@@ -0,0 +1,154 @@
+import { TranslationOptions } from './types';
+import { LocaleDescriptor, TranslationResponse } from './services';
+import { PublicModelInterface } from '../../../core/types';
+import { IKosDataModel, IKosIdentifiable, KosContext, KosCreationContext } from '../../../core';
+
+export declare const MODEL_TYPE = "translation-model";
+interface ResolveTranslationOptionsBase<T = string> {
+    context?: string;
+    defaultValue?: T;
+}
+interface ResolveTranslationsDataOptions<T = string> extends ResolveTranslationOptionsBase<T> {
+    data: Record<string, any> | string;
+}
+type ResolveTranslationsOptionsMap<T = string> = ResolveTranslationOptionsBase<T> & Record<string, string | number | boolean | undefined | null>;
+export type ResolveTranslationOptions<T = string> = ResolveTranslationsDataOptions<T> | ResolveTranslationsOptionsMap<T>;
+/**
+ * Translation - Individual namespace translations with automatic locale switching and interpolation.
+ *
+ * The Translation model provides access to localized text for a specific namespace within a KOS
+ * application. It handles locale switching, fallback chains, variable interpolation, and context-aware
+ * translations for building truly international device interfaces that adapt to user language preferences
+ * automatically.
+ *
+ * ## Key Features
+ * - **Namespace Isolation** - Translations organized by functional area or feature
+ * - **Automatic Locale Switching** - React to parent container locale changes
+ * - **Fallback Chains** - Graceful degradation through locale hierarchy (pt-BR → pt → es → en)
+ * - **Variable Interpolation** - Support for both template (`{{variable}}`) and macro (`__variable__`) substitution
+ * - **Context-Aware Keys** - Conditional translations based on context (e.g., `title_edit` vs `title`)
+ * - **Real-time Updates** - Automatic UI updates when locale or translations change
+ * - **Bundle Resolution** - Custom loading strategies for different deployment scenarios
+ *
+ * ## Variable Interpolation Patterns
+ * The model supports two interpolation patterns for dynamic content:
+ * - **Template Variables** (`{{variable}}`) - Context-based substitution passed via options
+ * - **Macro Variables** (`__variable__`) - Data-based substitution from nested objects
+ *
+ * ## Fallback Resolution
+ * When translations are missing, the system follows a sophisticated fallback chain:
+ * 1. **Current locale** (e.g., `pt-BR`)
+ * 2. **Parent locale** (e.g., `pt`)
+ * 3. **Fallback locales** (configured per locale, e.g., `es`)
+ * 4. **Default locale** (typically `en`)
+ * 5. **Provided default value** or raw key
+ *
+ * ## Common Use Cases
+ * - **Feature-Specific UI** - Isolated translations for dashboards, settings, alerts
+ * - **Form Validation** - Localized error messages with variable interpolation
+ * - **Status Displays** - Dynamic content with device state and user context
+ * - **Multi-Language Interfaces** - Complete internationalization for global deployments
+ * - **Context-Aware Content** - Mode-specific text (create vs edit, online vs offline)
+ * - **Rich Text Support** - Integration with Trans component for formatted content
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const statusTranslations = Translation.instance('device-status')
+ *   .options({
+ *     namespace: 'device-status',
+ *     currentLocale: 'es',
+ *     defaultLocale: 'en',
+ *     descriptor: {
+ *       'es': { fallbacks: ['en'] },
+ *       'en': { fallbacks: [] }
+ *     }
+ *   })
+ *   .build();
+ *
+ * // Resolve localized keys with fallback support
+ * const title = statusTranslations.resolveKey('title');
+ * ```
+ *
+ * @group KOS Model
+ * @category i18n
+ * @useDeclaredType
+ *
+ * @see {@link TranslationOptions} - Configuration options for Translation instances
+ * @see {@link TranslationContainerModel} - Container for managing multiple translation namespaces
+ * @see {@link useKosTranslation} - React hook for accessing translations in components
+ * @see {@link Trans} - React component for rich text translations with markup
+ */
+export type TranslationModel = PublicModelInterface<TranslationModelImpl>;
+export declare const expandMacros: (text: string, data: Record<string, any>) => any;
+export declare const replaceText: (text: string, data: Record<string, any>, context?: Record<string, any>) => any;
+export declare class TranslationModelImpl implements IKosDataModel, IKosIdentifiable {
+    /** Unique identifier for the model instance */
+    id: string;
+    /** Namespace identifier for translation key isolation */
+    namespace: string;
+    /** Locale descriptor configuration mapping locales to fallback chains */
+    descriptor: Record<string, LocaleDescriptor>;
+    /** Default locale to use when no translation is found in fallback chain */
+    defaultLocale: string;
+    /** Currently active locale for translation resolution */
+    currentLocale: string;
+    /** Custom bundle resolver for loading translation data */
+    bundleResolver?: (namespace: string, locale: string, context?: KosContext) => Promise<TranslationResponse>;
+    /** Flattened translation data for efficient key lookup */
+    private data;
+    /** Context logger for debugging and diagnostics */
+    private logger;
+    /** Path resolver function for translation bundle location */
+    private resolver;
+    /** Reaction disposer for locale change monitoring */
+    private disposer?;
+    /** Parent translation container reference for namespace resolution */
+    private context;
+    /** Base URL for loading translation resources */
+    private rootUrl?;
+    constructor(modelId: string, options: TranslationOptions, context: KosCreationContext);
+    /**
+     * Builds the fallback chain for a given locale.
+     * @param locale The locale to get translation fallback chain for
+     * @returns Array of locales in priority order
+     * @private
+     */
+    getTranslationLocales(locale: string): string[];
+    /**
+     * Loads and merges translations for all locales in the fallback chain.
+     * @private
+     */
+    private loadTranslations;
+    /**
+     * @internal
+     */
+    init(): Promise<void>;
+    /**
+     * Checks if a translation key exists in the current namespace.
+     * @param _key Translation key, optionally with namespace prefix
+     * @returns True if the key exists
+     */
+    exists(_key: string): any;
+    /**
+     * Resolves a translation key with optional variable interpolation.
+     * @param _key Translation key, optionally with namespace prefix
+     * @param options Options for interpolation and fallback
+     * @returns Resolved translation string or array
+     */
+    resolveKey<T = string>(_key: string, options?: ResolveTranslationOptions<T> | string): any;
+    /**
+     * @internal
+     */
+    unload(): void;
+    /**
+     * @internal
+     */
+    load(): Promise<void>;
+    /**
+     * @internal
+     */
+    ready(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=translation-model.d.ts.map

package/models/models/translation/translation-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/translation/translation-model.ts"],"names":[],"mappings":"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"}

package/models/models/translation/translation-registration.d.ts

@@ -0,0 +1,85 @@
+import { TranslationOptions } from './types';
+import { TranslationModel } from './translation-model';
+import { KosModelRegistrationBean } from '../../../core';
+
+/**
+ * # Translation
+ *
+ * The registration bean includes convenience methods for creating and working with TranslationModel instances.
+ *
+ * ## type
+ * The type property is a string that identifies the model type.
+ * The type is used to identify the model type in the model registry and to narrow down the model type in type predicates.  It's most frequently
+ * used when declaring dependencies on models.
+ *
+ * @example
+ * ```typescript
+ *
+ * @kosDependency({modelType: Translation.type, id: "translationId"})
+ * private translationModel: TranslationModel;
+ * ```
+ *
+ *
+ * ## factory
+ *
+ * The factory method creates a factory function that can be used to create new TranslationModel instances.
+ *
+ 
+ * The factory function is a curried function that takes the model id as the first argument and the options as the second argument.
+ *
+ * If a model with the specified id already exists, the factory function will return the existing model.  The options will be ignored
+ * in this case and the existing model will be returned in its current state.
+ *
+ * @example
+ * ```typescript
+ * const model = Translation.factory("translationId")({
+ *   // Add option data
+ * });
+ * ```
+ 
+
+ *
+ * ## predicate
+ *
+ * [Typescript type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) function that will identify and narrow down a model to a TranslationModel.
+ *
+ * @example
+ * ```typescript
+ *
+ * const model: IKosDataModel = ...; // some model
+ *
+ * if (Translation.predicate(model)) {
+ *    // if the function evaluates to true, the model is narrowed down to TranslationModel
+ *    // and the compiler will know that the model has the TranslationModel interface
+ *    model.updateAvailability(false);
+ * }
+ * ```
+ *
+ * ## registration
+ *
+ * The registration property is an object that can be used to simplify registration of the model with the model registry.  The registration object
+ * can be spread into the model registration and provides all of the required information to register the model implementation class against the model type.
+ *
+ *
+ * @example
+ *
+ * In an application registration file you can declare the model registration as follows:
+ *
+ * **registration.ts**
+ * ```typescript
+ * import { Translation } from "@kosdev-code/kos-dispense-sdk";
+ * ...
+ * import { ExtensionManager, IKosRegistry } from "@kosdev-code/kos-ui-sdk";
+ * export const kosModels: IKosRegistry["models"] = {
+ *  ...Translation.registration,
+ * };
+ * ```
+ *
+ * ## registration.singleton
+ 
+ * The translation model is NOT a singleton model.  This means that each time the factory function is called with a unique ID, a new model instance will be created.
+ * If the factory function is called with an ID that already exists, the existing model will be returned.
+ 
+ * */
+export declare const Translation: Readonly<KosModelRegistrationBean<TranslationModel, TranslationOptions>>;
+//# sourceMappingURL=translation-registration.d.ts.map

package/models/models/translation/translation-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-registration.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/translation/translation-registration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA8EK;AACL,eAAO,MAAM,WAAW,EAAE,QAAQ,CAChC,wBAAwB,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAW/D,CAAC"}