Interface TranslationModel

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

Example: Basic Usage

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');

Use Declared Type

See

  • TranslationOptions - Configuration options for Translation instances
  • TranslationContainerModel - Container for managing multiple translation namespaces
  • useKosTranslation - React hook for accessing translations in components
  • Trans - React component for rich text translations with markup
interface TranslationModel {
    id: string;
    namespace: string;
    descriptor: Record<string, LocaleDescriptor>;
    defaultLocale: string;
    currentLocale: string;
    exists(_key): any;
    resolveKey<T>(_key, options?): any;
    bundleResolver?: ((namespace, locale, context?) => Promise<TranslationResponse>);
}

Methods

exists resolveKey

Properties

id namespace descriptor defaultLocale currentLocale bundleResolver?

Methods

exists

  • exists(_key): any

  • Checks if a translation key exists in the current namespace.

    Parameters

    • _key: string

      Translation key, optionally with namespace prefix

    Returns any

    True if the key exists

resolveKey

  • resolveKey<T>(_key, options?): any

  • Resolves a translation key with optional variable interpolation.

    Type Parameters

    • T = string

    Parameters

    • _key: string

      Translation key, optionally with namespace prefix

    • Optional options: string | ResolveTranslationOptions<T>

      Options for interpolation and fallback

    Returns any

    Resolved translation string or array

Properties

id

id: string

Unique identifier for the model instance

namespace

namespace: string

Namespace identifier for translation key isolation

descriptor

descriptor: Record<string, LocaleDescriptor>

Locale descriptor configuration mapping locales to fallback chains

defaultLocale

defaultLocale: string

Default locale to use when no translation is found in fallback chain

currentLocale

currentLocale: string

Currently active locale for translation resolution

Optional bundleResolver

bundleResolver?: ((namespace, locale, context?) => Promise<TranslationResponse>)

Custom bundle resolver for loading translation data

Type declaration

    • (namespace, locale, context?): Promise<TranslationResponse>

    • Parameters

      • namespace: string
      • locale: string
      • Optional context: KosContext

      Returns Promise<TranslationResponse>

Settings

Member Visibility

Theme

On This Page

existsresolveKeyidnamespacedescriptordefaultLocalecurrentLocalebundleResolver