A Complete Architecture Using Angular 22, ngx-translate, RxJS, and Tailwind CSS
1. Introduction
Localization is often treated as a simple feature: add a language dropdown, create two JSON files, and replace hardcoded strings with translation keys.
However, this approach is not sufficient for a real-world application.
Imagine building an enterprise dashboard used by employees in different countries. Some users prefer English, while others prefer Arabic. When a user changes the language, the entire application must respond immediately.
This includes:
- Navigation menus and page titles.
- Dashboard statistics and product information.
- Form labels, placeholders, and validation messages.
- Dates, currencies, and numbers.
- Text direction and layout.
- Notifications and dynamically generated messages.
- Content loaded from APIs.
A production-ready localization system must also consider performance, maintainability, lazy loading, caching, fallback languages, and testing.
In this article, we'll build a realistic Angular application with English and Arabic support and design its localization architecture as if we were implementing it for a real company.
By the end, we'll have a system that supports runtime language switching, RTL/LTR layouts, feature-based translation files, and a reusable translation service.
2. Understanding Internationalization and Localization
Before writing code, it's important to understand two concepts.
Internationalization (i18n)
Internationalization is the process of designing an application so it can support multiple languages and regional conventions without requiring major code changes.
For example, an application should not assume that:
- Every language reads from left to right.
- Every country uses the same date format.
- Every currency uses the same symbol.
- Every language has the same pluralization rules.
Internationalization focuses on preparing the application for different cultures and languages.
Localization (l10n)
Localization is the process of adapting an internationalized application to a specific language or region.
For example:
| English | Arabic |
|---|---|
| Dashboard | لوحة التحكم |
| Products | المنتجات |
| Settings | الإعدادات |
| Welcome back | مرحباً بعودتك |
| Save changes | حفظ التغييرات |
Localization also includes date formatting, number formatting, currency conventions, and text direction.
The distinction is important:
Internationalization is an architectural decision. Localization is the implementation of that decision for specific languages and regions.
3. Project Architecture
We'll build a small enterprise dashboard called Global Commerce Dashboard.
It will contain three main pages:
- Dashboard: displays statistics and recent activity.
- Products: displays a list of products.
- Product Details: displays information about a selected product.
We'll also implement shared components such as:
- Navbar.
- Language Switcher.
- Reusable Button.
- Reusable Input.
Why Feature-Based Architecture?
A common mistake is organizing an entire application by technical type:
components/ services/ models/ pages/ pipes/ This structure may work for small applications, but it becomes difficult to maintain when features grow.
Instead, we'll organize the application around business features.
Each feature owns its components, routes, models, and feature-specific translations.
Project Structure
src/ │ ├── app/ │ │ │ ├── core/ │ │ ├── localization/ │ │ │ ├── translation.service.ts │ │ │ ├── translation.types.ts │ │ │ ├── missing-translation.handler.ts │ │ │ └── locale.config.ts │ │ │ │ │ ├── interceptors/ │ │ └── guards/ │ │ │ ├── shared/ │ │ ├── components/ │ │ │ ├── navbar/ │ │ │ ├── language-switcher/ │ │ │ ├── button/ │ │ │ └── input/ │ │ │ │ │ └── pipes/ │ │ │ ├── features/ │ │ ├── dashboard/ │ │ │ ├── dashboard.component.ts │ │ │ └── dashboard.routes.ts │ │ │ │ │ └── products/ │ │ ├── components/ │ │ ├── pages/ │ │ │ ├── products-list/ │ │ │ └── product-details/ │ │ ├── models/ │ │ └── products.routes.ts │ │ │ ├── app.component.ts │ ├── app.config.ts │ └── app.routes.ts │ ├── assets/ │ └── i18n/ │ ├── en.json │ ├── ar.json │ │ │ └── features/ │ └── products/ │ ├── en.json │ └── ar.json │ └── styles.css Notice that we're separating global translations from feature translations.
This is important because a large application may have dozens of features, and loading every translation file during application startup would waste bandwidth and increase initial loading time.
4. Choosing the Translation Library
Angular provides two main approaches to internationalization.
Angular Built-in i18n
Angular's built-in i18n system is useful when translations are managed during the build process.
It works particularly well for applications that:
- Have predefined language versions.
- Don't need frequent runtime language changes.
- Prefer separate localized application builds.
However, runtime switching between languages requires a different deployment and application architecture.
ngx-translate
For this application, we'll use ngx-translate.
It provides:
- Runtime language switching.
- JSON-based translation files.
- Lazy loading.
- Interpolation.
- Translation fallback.
- Reactive translation updates.
- Standalone provider APIs.
- Hierarchical translation services for lazy-loaded features.
Another important detail is that ngx-translate v18 uses Angular Signals internally while still supporting RxJS-based APIs.
We'll use RxJS in our application-level abstraction to expose a consistent reactive interface.
Architecture decision: ngx-translate handles the translation engine, while our TranslationService handles application-specific localization behavior.
This separation prevents components from depending directly on the translation library.
5. Project Setup
Create the Angular application:
ng new global-commerce-dashboard \ --standalone \ --routing \ --style css \ --strict cd global-commerce-dashboard Install the translation dependencies:
npm install @ngx-translate/core @ngx-translate/http-loader Install Tailwind CSS:
ng add tailwindcss Angular CLI provides an official Tailwind integration that configures the required dependencies and styles.
We can also verify the Angular version:
ng version For this implementation, use the compatible ngx-translate v18 release.
Why Strict Mode?
Strict mode helps detect problems before runtime.
For example:
- Incorrect types in translation parameters.
- Nullable values.
- Invalid component inputs.
- Inconsistent service contracts.
Localization code frequently handles dynamic values, so strict typing is particularly valuable.
6. Designing the Translation Files
We'll start with the global translation files.
src/assets/i18n/en.json
{ "app": { "name": "Global Commerce", "welcome": "Welcome back, {{name}}", "loading": "Loading...", "save": "Save", "cancel": "Cancel", "search": "Search" }, "navigation": { "dashboard": "Dashboard", "products": "Products", "settings": "Settings" }, "dashboard": { "title": "Dashboard", "subtitle": "Here's what's happening with your business.", "statistics": { "revenue": "Total Revenue", "orders": "Total Orders", "customers": "Customers", "products": "Products" }, "activity": { "title": "Recent Activity" } }, "common": { "actions": "Actions", "viewDetails": "View Details", "noData": "No data available", "error": "Something went wrong" } } src/assets/i18n/ar.json
{ "app": { "name": "التجارة العالمية", "welcome": "مرحباً بعودتك، {{name}}", "loading": "جاري التحميل...", "save": "حفظ", "cancel": "إلغاء", "search": "بحث" }, "navigation": { "dashboard": "لوحة التحكم", "products": "المنتجات", "settings": "الإعدادات" }, "dashboard": { "title": "لوحة التحكم", "subtitle": "إليك آخر المستجدات المتعلقة بنشاطك التجاري.", "statistics": { "revenue": "إجمالي الإيرادات", "orders": "إجمالي الطلبات", "customers": "العملاء", "products": "المنتجات" }, "activity": { "title": "النشاط الأخير" } }, "common": { "actions": "الإجراءات", "viewDetails": "عرض التفاصيل", "noData": "لا توجد بيانات", "error": "حدث خطأ غير متوقع" } } Why Nested Translation Keys?
Instead of creating hundreds of unrelated keys:
{ "dashboardTitle": "Dashboard", "dashboardRevenue": "Total Revenue", "dashboardOrders": "Total Orders" } We organize translations by domain:
{ "dashboard": { "title": "Dashboard", "statistics": { "revenue": "Total Revenue", "orders": "Total Orders" } } } This improves readability and makes the translation structure easier to maintain.
It also makes it easier to compare the English and Arabic dictionaries.
7. Configuring ngx-translate
Now we'll configure the translation engine.
app.config.ts
import { ApplicationConfig, inject, provideAppInitializer } from '@angular/core'; import { provideHttpClient } from '@angular/common/http'; import { provideRouter } from '@angular/router'; import { provideTranslateService, TranslateService } from '@ngx-translate/core'; import { provideTranslateHttpLoader } from '@ngx-translate/http-loader'; import { firstValueFrom } from 'rxjs'; import { routes } from './app.routes'; import { TranslationService } from './core/localization/translation.service'; export const appConfig: ApplicationConfig = { providers: [ provideRouter(routes), provideHttpClient(), provideTranslateService({ loader: provideTranslateHttpLoader({ prefix: '/assets/i18n/', suffix: '.json' }), lang: 'en', fallbackLang: 'en' }), provideAppInitializer(() => { const translationService = inject(TranslationService); return firstValueFrom( translationService.initialize() ); }) ] }; Understanding the Configuration
provideTranslateService() registers the root translation service.
The HTTP loader retrieves translation files using the selected language.
For example:
/assets/i18n/en.json /assets/i18n/ar.json The fallbackLang option defines the language used when a translation is missing from the active language.
The application initializer ensures that the preferred language is loaded before the application starts rendering its main content.
This helps prevent untranslated content from briefly appearing during startup.
8. Creating a TranslationService Abstraction
This is one of the most important architectural decisions.
We don't want every component to inject TranslateService and independently manage:
- localStorage.
- Language validation.
- RTL/LTR configuration.
- Browser language detection.
- Language switching.
- Error handling.
Instead, we'll create a centralized abstraction.
8.1 Translation Types
translation.types.ts
export const SUPPORTED_LANGUAGES = [ 'en', 'ar' ] as const; export type SupportedLanguage = typeof SUPPORTED_LANGUAGES[number]; export type TextDirection = 'ltr' | 'rtl'; export interface LanguageConfig { code: SupportedLanguage; label: string; direction: TextDirection; locale: string; } export const LANGUAGE_CONFIG: Record< SupportedLanguage, LanguageConfig > = { en: { code: 'en', label: 'English', direction: 'ltr', locale: 'en-US' }, ar: { code: 'ar', label: 'العربية', direction: 'rtl', locale: 'ar-EG' } }; Why define a language configuration instead of using simple strings?
Because language is more than a translation file.
Each language may have its own:
- Text direction.
- Date conventions.
- Number formatting.
- Currency conventions.
- Regional settings.
Centralizing these properties makes it easier to add new languages later.
8.2 Implementing the Service
translation.service.ts
import { Injectable, inject, signal } from '@angular/core'; import { TranslateService } from '@ngx-translate/core'; import { BehaviorSubject, Observable, catchError, from, map, of, switchMap, tap } from 'rxjs'; import { LANGUAGE_CONFIG, LanguageConfig, SupportedLanguage } from './translation.types'; @Injectable({ providedIn: 'root' }) export class TranslationService { private readonly translate = inject(TranslateService); private readonly storageKey = 'app-language'; private readonly currentLanguageSubject = new BehaviorSubject<SupportedLanguage>('en'); readonly currentLanguage$ = this.currentLanguageSubject.asObservable(); readonly currentLanguage = signal<SupportedLanguage>('en'); readonly direction = signal<'ltr' | 'rtl'>('ltr'); readonly locale = signal('en-US'); readonly languages = Object.values(LANGUAGE_CONFIG); initialize(): Observable<SupportedLanguage> { const language = this.getInitialLanguage(); return this.translate .setFallbackLang('en') .pipe( switchMap(() => this.translate.use(language)), map(() => language), tap(() => this.applyLanguage(language)) ); } switchLanguage( language: SupportedLanguage ): Observable<SupportedLanguage> { if (!LANGUAGE_CONFIG[language]) { return of(this.currentLanguage()); } return this.translate.use(language).pipe( map(() => language), tap(() => this.applyLanguage(language)), catchError(error => { console.error('Language switching failed', error); return of(this.currentLanguage()); }) ); } private applyLanguage( language: SupportedLanguage ): void { const config: LanguageConfig = LANGUAGE_CONFIG[language]; this.currentLanguage.set(language); this.direction.set(config.direction); this.locale.set(config.locale); this.currentLanguageSubject.next(language); localStorage.setItem( this.storageKey, language ); document.documentElement.lang = language; document.documentElement.dir = config.direction; } private getInitialLanguage(): SupportedLanguage { const savedLanguage = localStorage.getItem(this.storageKey); if (this.isSupportedLanguage(savedLanguage)) { return savedLanguage; } const browserLanguage = navigator.language.split('-')[0]; if (this.isSupportedLanguage(browserLanguage)) { return browserLanguage; } return 'en'; } private isSupportedLanguage( language: string | null ): language is SupportedLanguage { return ( language !== null && Object.prototype.hasOwnProperty.call( LANGUAGE_CONFIG, language ) ); } } Why Use BehaviorSubject?
We need a reactive stream that notifies components when the active language changes.
For example:
this.translationService.currentLanguage$ .subscribe(language => { console.log('Current language:', language); }); A BehaviorSubject immediately emits the latest language to new subscribers.
This is useful for components that are created after the user has already changed the language.
We also expose Signals for convenient integration with Angular templates.
Why Apply the Language After Loading?
Notice the order:
return this.translate.use(language).pipe( map(() => language), tap(() => this.applyLanguage(language)) ); We first load the translation dictionary, then update the application's language state.
This avoids updating the UI direction while the requested translation is still loading.
Production Consideration: SSR
The example above targets a browser-rendered application.
If we introduce Angular SSR, direct access to localStorage, navigator, and document must be protected using Angular's platform abstractions.
Also, user-specific language state must not be shared between server requests.
9. Implementing the Language Switcher
Now we can build a reusable component.
language-switcher.component.ts
import { Component, inject } from '@angular/core'; import { TranslatePipe } from '@ngx-translate/core'; import { TranslationService } from '../../../core/localization/translation.service'; import { SupportedLanguage } from '../../../core/localization/translation.types'; @Component({ selector: 'app-language-switcher', standalone: true, imports: [TranslatePipe], template: ` <div class="flex items-center gap-2"> <button type="button" (click)="changeLanguage('en')" [class.font-bold]=" translation.currentLanguage() === 'en' " aria-label="Switch to English" > English </button> <span aria-hidden="true">|</span> <button type="button" (click)="changeLanguage('ar')" [class.font-bold]=" translation.currentLanguage() === 'ar' " aria-label="التغيير إلى العربية" > العربية </button> </div> ` }) export class LanguageSwitcherComponent { readonly translation = inject(TranslationService); changeLanguage(language: SupportedLanguage): void { this.translation.switchLanguage(language) .subscribe(); } } Why Is This Component Reusable?
It doesn't know anything about:
- Dashboard.
- Products.
- Routing.
- Translation file locations.
- localStorage implementation.
Its only responsibility is allowing users to select a language.
This is an example of the Single Responsibility Principle.
10. Building the Navbar
The navbar will display translated navigation items and the language switcher.
navbar.component.ts
import { Component } from '@angular/core'; import { RouterLink, RouterLinkActive } from '@angular/router'; import { TranslatePipe } from '@ngx-translate/core'; import { LanguageSwitcherComponent } from '../language-switcher/language-switcher.component'; @Component({ selector: 'app-navbar', standalone: true, imports: [ RouterLink, RouterLinkActive, TranslatePipe, LanguageSwitcherComponent ], template: ` <header class="border-b bg-white px-6 py-4"> <nav class="flex items-center justify-between"> <a routerLink="/dashboard" class="text-xl font-bold" > {{ 'app.name' | translate }} </a> <div class="flex items-center gap-6"> <a routerLink="/dashboard" routerLinkActive="text-blue-600" > {{ 'navigation.dashboard' | translate }} </a> <a routerLink="/products" routerLinkActive="text-blue-600" > {{ 'navigation.products' | translate }} </a> <app-language-switcher /> </div> </nav> </header> ` }) export class NavbarComponent {} Notice that the navbar doesn't manually subscribe to language changes.
The translation pipe handles reactive updates.
When the selected language changes, Angular updates the displayed text.
11. Creating the Main Application Layout
app.component.ts
import { Component, inject } from '@angular/core'; import { RouterOutlet } from '@angular/router'; import { NavbarComponent } from './shared/components/navbar/navbar.component'Source:https://dev.to/abanoubkerols/building-a-production-ready-localization-and-internationalization-system-in-angular-325nRelated posts
Charge only for successful results in a pay-per-event Apify Actor (and test it locally)
Submission 19 of 18 runs: the benchmark where Vow and TypeScript tied
Chrome's WebRTC IP policy skips extension pages, and they get raw IPs instead of mDNS names
