Ziegel API Docs

Appearance

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 ​

bash
npm install @breadstone/ziegel-platform-localization

Usage ​

Basic Setup ​

typescript
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 ​

typescript
// 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 ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

  • @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

Released under the MIT License.

© 2026 Ziegel Platform