@flusys/ng-localization

Database-driven i18n for FLUSYS Angular apps — translations loaded from the backend at startup, signal-reactive TranslatePipe, RTL/LTR auto-switching, and a built-in language selector for the topbar.

Installation

npm install @flusys/ng-localization

1. Register Providers

Call provideLocalization() once in app.config.ts. It registers ``(consumed byTranslatePipefromng-shared), an APP_INITIALIZER that loads translations before the first render, and optionally the topbar language selector.

// app.config.ts
import { provideLocalization } from "@flusys/ng-localization";

export const appConfig: ApplicationConfig = {
  providers: [
    provideLocalization({
      defaultLanguageCode: "en", // required — fallback when no saved preference
      loadStrategy: "modules", // optional — 'modules' (default) or 'all'
      initialModules: [], // optional — modules to pre-load at startup
      enableLayoutSelector: true, // optional — renders language picker in AppTopbar
    }),
  ],
};

loadStrategy: 'modules' defers loading until a route resolver requests a module. Use 'all' only for small translation sets.

2. Use TranslatePipe in Templates

Import TranslatePipe from @flusys/ng-shared (not from this package). The pipe is signal-reactive and re-renders automatically on language change. language

import { TranslatePipe } from "@flusys/ng-shared";

@Component({
  imports: [TranslatePipe],
  template: `
    <h1>{{ "dashboard.title" | translate }}</h1>
    <button>{{ "shared.save" | translate }}</button>
    <input [placeholder]="'form.search.placeholder' | translate" />

    <!-- With interpolation -->
    <p>{{ "pagination.showing" | translate: { from: 1, to: 10, total: 100 } }}</p>
  `,
})
export class DashboardComponent {}

Translation values stored in the database use {{variableName}} syntax:

Key:   pagination.showing
Value: Showing {{from}}-{{to}} of {{total}} results

3. Load Translations Per Route (Module Strategy)

Use resolveTranslationModule() in your route definition so translations for a feature load before the page renders. Pass fallbackMessages so the UI works even without a backend.

// Inside a feature's routes file
import { resolveTranslationModule } from "@flusys/ng-shared";
import { MY_FEATURE_MESSAGES } from "./constants/messages";

export const MY_ROUTES: Routes = [
  {
    path: "",
    resolve: {
      translations: resolveTranslationModule({
        modules: ["myFeature"], // module name used by the backend
        fallbackMessages: MY_FEATURE_MESSAGES, // static fallback map
      }),
    },
    loadComponent: () => import("./my-feature-container.component").then((m) => m.MyFeatureContainerComponent),
    children: [
      /* ... */
    ],
  },
];

Already-loaded modules are cached — navigating back to the same route does not re-fetch.

4. Translate Imperatively in Services / Components

Inject TranslateService when you need a string outside a template (e.g., toast messages, computed labels).

import { inject } from "@angular/core";
import { TranslateService } from "@flusys/ng-localization";

export class MyComponent {
  private readonly translate = inject(TranslateService);

  // Synchronous — returns fallback key if not found
  getLabel(): string {
    return this.translate.translate("shared.save");
  }

  // With params
  getCountLabel(count: number): string {
    return this.translate.translate("items.count", { count });
  }

  // Signal-based — updates automatically on language change
  readonly pageTitle = this.translate.translateSignal("dashboard.title");

  // Read current language code
  readonly lang = this.translate.languageCode; // Signal<string>
}

5. Add Admin Routes (Language and Key Management)

// app.routes.ts
import { LOCALIZATION_ROUTES } from "@flusys/ng-localization";

export const routes: Routes = [
  {
    path: "localization",
    loadChildren: () => LOCALIZATION_ROUTES,
  },
];

RTL Support

When the user switches to an RTL language, LocalizationStateService sets document.documentElement.dir and lang automatically. Tailwind rtl: utility classes and component RTL support both activate from this single attribute change — no extra configuration needed.

License

MIT © FLUSYS