@breadstone/ziegel-platform-localization

A comprehensive localization management system for TypeScript applications that provides multi-language support, flexible content providers, and powerful text formatting capabilities.

Features

• Localization Manager: Central management of localized strings with culture-aware retrieval
• Multiple Providers: Support for map-based, HTTP-based, and composite localization sources
• Key Resolvers: Flexible key transformation with CamelCase, PascalCase, Snake_case, and kebab-case support
• Value Parsers: Format and reference parsing for dynamic content substitution
• Caching System: Intelligent caching for improved performance and reduced network calls
• Missing Handlers: Configurable fallback strategies for missing translations
• RxJS Integration: Reactive localization updates with observable patterns
• Builder Pattern: Fluent API for easy setup and configuration

Architecture

The localization system is built on several key components:

• LocalizationManager: Core service for retrieving and managing localized content
• ILocalizationProvider: Interface for content sources (HTTP, static maps, composite)
• IKeyResolver: Transforms keys between different naming conventions
• ILocalizationValueParser: Processes values for formatting and references
• ILocalizationCache: Manages cached translations for performance
• ICultureProvider: Provides current culture information and change notifications

Installation

npm install @breadstone/ziegel-platform-localization

Usage

Basic Setup

import {
    LocalizationManagerBuilder,
    MapLocalizationProvider,
    CamelCaseKeyResolver
} from '@breadstone/ziegel-platform-localization';

// Create a localization provider with translations
const provider = new MapLocalizationProvider(new Map([
    ['en-US', new Map([
        ['welcome_message', 'Welcome to our application!'],
        ['user_count', 'We have {0} active users']
    ])],
    ['de-DE', new Map([
        ['welcome_message', 'Willkommen in unserer Anwendung!'],
        ['user_count', 'Wir haben {0} aktive Benutzer']
    ])]
]));

// Build the localization manager
const manager = new LocalizationManagerBuilder()
    .withProvider(provider)
    .withKeyResolver(new CamelCaseKeyResolver())
    .build();

Retrieving Localized Strings

// Simple localization
const welcomeMessage = await manager.getLocalizedString('welcomeMessage');
console.log(welcomeMessage); // "Welcome to our application!"

// Formatted localization with parameters
const userMessage = await manager.getLocalizedString('userCount', 150);
console.log(userMessage); // "We have 150 active users"

HTTP-Based Localization

import {
    LocalizationManagerBuilder,
    LoaderLocalizationProvider,
    HttpLocalizationLoader
} from '@breadstone/ziegel-platform-localization';

const httpLoader = new HttpLocalizationLoader('/api/localization/{culture}.json');
const provider = new LoaderLocalizationProvider(httpLoader);

const manager = new LocalizationManagerBuilder()
    .withProvider(provider)
    .withCaching(true)
    .build();

Reactive Localization with RxJS

import { fromLocalizable } from '@breadstone/ziegel-platform-localization';
import { of } from 'rxjs';

// Create reactive localizable content
const localizable = {
    key: 'welcomeMessage',
    fallback: 'Welcome!',
    manager: manager
};

// Convert to observable
const localizedString$ = of(localizable).pipe(
    fromLocalizable()
);

localizedString$.subscribe(text => {
    console.log(text); // Localized string
});

Culture Changes

import { CultureProvider } from '@breadstone/ziegel-platform';

const cultureProvider = new CultureProvider();

// Listen for culture changes
cultureProvider.cultureChanged.add((newCulture) => {
    console.log(`Culture changed to: ${newCulture}`);
});

// Change culture
cultureProvider.setCulture('de-DE');

Composite Providers

import {
    CompositeLocalizationProvider,
    MapLocalizationProvider,
    LoaderLocalizationProvider
} from '@breadstone/ziegel-platform-localization';

// Combine multiple providers with fallback
const primaryProvider = new LoaderLocalizationProvider(httpLoader);
const fallbackProvider = new MapLocalizationProvider(fallbackTranslations);

const compositeProvider = new CompositeLocalizationProvider([
    primaryProvider,
    fallbackProvider
]);

Custom Missing Handlers

import {
    LocalizationManagerBuilder,
    IMissingLocalizationHandlerFunc
} from '@breadstone/ziegel-platform-localization';

const customMissingHandler: IMissingLocalizationHandlerFunc = (key, culture) => {
    console.warn(`Missing translation for key: ${key} in culture: ${culture}`);
    return `[${key}]`; // Return key in brackets as fallback
};

const manager = new LocalizationManagerBuilder()
    .withProvider(provider)
    .withMissingHandler(customMissingHandler)
    .build();

Package import points

import {
    // Core interfaces
    ILocalizationManager,
    ILocalizable,
    ILocalizationProvider,
    IKeyResolver,

    // Main classes
    LocalizationManager,
    LocalizationManagerBuilder,
    LocalizationCache,

    // Providers
    MapLocalizationProvider,
    LoaderLocalizationProvider,
    CompositeLocalizationProvider,
    HttpLocalizationLoader,

    // Key resolvers
    CamelCaseKeyResolver,
    PascalCaseKeyResolver,
    SnakeCaseKeyResolver,
    KebabCaseKeyResolver,

    // Value parsers
    FormatLocalizationValueParser,
    RefLocalizationValueParser,

    // RxJS extensions
    fromLocalizable,
    loc,
    localize
} from '@breadstone/ziegel-platform-localization';

API Documentation

For detailed API documentation, visit: API Docs

Related Packages

• @breadstone/ziegel-platform: Core platform services and culture management
• @breadstone/ziegel-platform-http: HTTP client functionality for remote localization
• @breadstone/ziegel-core: Fundamental utilities and string manipulation
• @breadstone/ziegel-platform-logging: Logging infrastructure for debug information

License

MIT

Issues

Report issues at: GitHub Issues