Packages

@xtaskjs/internationalization

Request-aware translations, locale fallback, namespace loading, and DI-friendly formatting services.

npm install @xtaskjs/internationalization reflect-metadata Package path: packages/internationalization

Overview

What this package owns in the runtime

Internationalization adds request-scoped locale resolution, translation lookup, pluralization, and formatting helpers to the xtask lifecycle. It registers locale services before controllers resolve and exposes an injectable service for controllers, views, and domain presenters.

What it provides

Request-aware translations with locale fallback and exact-count pluralization.
Async namespace loading for feature-specific translation bundles.
Built-in number, currency, date, and datetime formatting with optional custom formatters.
InjectInternationalizationService() exposes locale-aware translation and formatting inside DI-managed classes.

How it fits

Initializes automatically before container lifecycle listeners are resolved during CreateApplication().
Resolves locale from query parameters and request headers, and can be extended with custom resolvers.
Used by this website and by the 09-internationalization_app and 10-internationalization_express_app samples.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

4/5

Dependency Injection

4/5

Localization

5/5

Rendering

4/5

HTTP Delivery

3/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Register locales, formatters, fallback settings, and optional locale resolvers so translation rules are known before request handling starts.

During CreateApplication()

Internationalization initializes request-aware locale services before controllers and views are resolved, enabling injected translations and formatting from the first request.

During app.close()

The lifecycle manager releases runtime translation state together with the rest of the application services.

API Surface

Representative exports from the upstream package

Configuration and locales

configureInternationalization
Internationalization
registerInternationalizationLocale
InternationalizationLocale
InternationalizationResolver

Translation runtime

InternationalizationService
InjectInternationalizationService
InjectI18nService
runWithInternationalizationContext

Formatting and lifecycle

registerInternationalizationFormatter
InjectInternationalizationLifecycleManager
InjectI18nLifecycleManager
initializeInternationalizationIntegration
shutdownInternationalizationIntegration

Usage

Typical adoption flow

1. Configure locales and fallbacks

2. Resolve locale from the request

Use query parameters, Accept-Language, cookies, or custom resolvers to make the current locale part of request context.

3. Inject translations into pages and services

Call the injected service inside controllers, views, presenters, and domain helpers so all formatting stays consistent.

Example

Reference snippet

Locale registration plus injected translations

import { Service } from "@xtaskjs/core";
import {
  InjectInternationalizationService,
  InternationalizationService,
  configureInternationalization,
  registerInternationalizationLocale,
} from "@xtaskjs/internationalization";

configureInternationalization({
  defaultLocale: "en-US",
  fallbackLocale: "en-US",
});

registerInternationalizationLocale({
  locale: "en-US",
  translations: { checkout: { total: "Total: {{amount, currency}}" } },
});

@Service()
export class CheckoutPresenter {
  constructor(
    @InjectInternationalizationService()
    private readonly intl: InternationalizationService
  ) {}

  presentTotal(amount: number) {
    return this.intl.t("checkout.total", { params: { amount } });
  }
}

Samples

Official samples to inspect next

Reference samples: 09-internationalization_app and 10-internationalization_express_app