@weblocale/angular

Light, flexible Angular localization library supporting Angular 15+ standalone APIs & legacy NgModule architectures. Provides WeblocaleService, weblocale Pipe, and weblocale Directive with automatic document language & metadata synchronization.

Features

• ⚡ Standalone First: Seamless registration via provideWeblocale() for Angular 15+ / 17-21.
• 📦 NgModule Support: Backwards compatible with WeblocaleAngularModule.forRoot().
• 🔀 Dynamic Language Switching: Reactively updates active language, template bindings, and local storage (localStorage).
• 🌐 Document & Head Synchronization: Syncs document.documentElement.lang, document.title, and <meta> tags automatically.
• 🧩 Pipe & Directive: Use {{ 'key' | weblocale }} or <span weblocale="key"></span> in templates.

Installation

npm install @weblocale/angular

Quick Start

1. Standalone Setup (Angular 15+)

Register provideWeblocale in app.config.ts:

import { ApplicationConfig } from '@angular/core';
import { provideWeblocale } from '@weblocale/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideWeblocale({
      translations: {
        en: {
          'app.title': 'My Application',
          'welcome.message': 'Welcome to our platform!'
        },
        es: {
          'app.title': 'Mi Aplicación',
          'welcome.message': '¡Bienvenido a nuestra plataforma!'
        }
      },
      config: {
        defaultLanguage: 'en',
        storageKey: 'app-lang',
        documentTitleKey: 'app.title'
      }
    })
  ]
};

2. NgModule Setup (Legacy Apps)

In app.module.ts:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { WeblocaleAngularModule } from '@weblocale/angular';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    WeblocaleAngularModule.forRoot({
      translations: {
        en: { 'app.title': 'My Application' },
        es: { 'app.title': 'Mi Aplicación' }
      },
      config: {
        defaultLanguage: 'en'
      }
    })
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

Usage in Components & Templates

Import Pipe or Directive in Standalone Components

import { Component } from '@angular/core';
import { WeblocalePipe, WeblocaleDirective, WeblocaleService } from '@weblocale/angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [WeblocalePipe, WeblocaleDirective],
  template: `
    <!-- Using Pipe -->
    <h1>{{ 'app.title' | weblocale }}</h1>

    <!-- Using Directive -->
    <p weblocale="welcome.message"></p>

    <!-- Language Selector -->
    <div class="lang-picker">
      @for (lang of languages; track lang.value) {
        <button 
          [class.active]="lang.active" 
          (click)="setLang(lang.value)">
          {{ lang.title }}
        </button>
      }
    </div>
  `
})
export class AppComponent {
  languages = this.weblocaleService.getLanguages();

  constructor(private weblocaleService: WeblocaleService) {}

  setLang(lang: string) {
    this.weblocaleService.setLanguage(lang);
  }
}

Service API (WeblocaleService)

| Method / Property | Return Type | Description | |---|---|---| | translate(key: string) | string | Returns translated string for current language (falls back to default language if missing). | | setLanguage(code: string) | void | Changes active language, saves choice to localStorage, and syncs document title/meta tags. | | getLanguage() | string | Returns current active language code. | | getLanguages() | WeblocaleLanguageState[] | Returns array of configured languages with active state. | | onChangeLanguage | Subject<string> | RxJS Subject emitting whenever the active language changes. | | init() | void | Manually applies document title & metadata tags for the current language. |

Example App

An integration example is included in the example/ directory:

# Run the Angular 21 ToDo example application
cd example
npm install
npm start

Publishing

For publishing instructions to npmjs.com, see the Publishing Guide.

License

MIT © Weblocale