baher-translate

Lightweight Angular Translation Library powered by Angular Signals.

🇺🇸 English Documentation

Overview

baher-translate is a lightweight Angular translation library built for modern Angular applications.

The library uses Angular Signals internally and provides a simple API for loading, managing, and switching application languages.

The package has been successfully tested with:

• Angular 20
• Client Side Rendering (CSR)
• Server Side Rendering (SSR)
• NX Workspace
• Standalone Angular applications

Features

• Angular Signals support
• Angular 20 compatible
• SSR compatible
• CSR compatible
• Standalone Components support
• Dynamic language switching
• Configurable translation loader path
• Nested translation keys
• Lightweight implementation
• TypeScript support
• Dependency Injection friendly
• NX Monorepo ready
• No external translation library dependency

Installation

npm install baher-translate

Translation Files Structure

Example:

public/
└── i18n/
    ├── en.json
    └── ar.json

Example Translation Files

en.json

{
  "app": {
    "title": "Baher Application",
    "description": "Modern Angular application"
  },
  "menu": {
    "home": "Home",
    "about": "About",
    "contact": "Contact"
  }
}

ar.json

{
  "app": {
    "title": "تطبيق باهر",
    "description": "تطبيق Angular حديث"
  },
  "menu": {
    "home": "الرئيسية",
    "about": "من نحن",
    "contact": "تواصل معنا"
  }
}

Configuration

app.config.ts

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideBaherTranslate } from 'baher-translate';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),

    provideBaherTranslate({
      defaultLanguage: 'en',
      supportedLanguages: ['en', 'ar'],
      loaderPath: 'public/i18n/'
    })
  ]
};

Using BaherTranslateService

import { Component, inject } from '@angular/core';
import { BaherTranslateService } from 'baher-translate';

@Component({
  selector: 'app-root',
  standalone: true,
  template: `
    <h1>{{ title() }}</h1>

    <button type="button" (click)="changeLanguage('en')">
      English
    </button>

    <button type="button" (click)="changeLanguage('ar')">
      العربية
    </button>
  `
})
export class AppComponent {
  private readonly translate = inject(BaherTranslateService);

  title = () => this.translate.instant('app.title');

  changeLanguage(language: string): void {
    this.translate.setLanguage(language);
  }
}

Using The Pipe

Import Pipe

import { BaherTranslatePipe } from 'baher-translate';

Component Example

import { Component } from '@angular/core';
import { BaherTranslatePipe } from 'baher-translate';

@Component({
  selector: 'app-home',
  standalone: true,
  imports: [BaherTranslatePipe],
  template: `
    <h1>{{ 'app.title' | baherTranslate }}</h1>
    <p>{{ 'app.description' | baherTranslate }}</p>
  `
})
export class HomeComponent {}

Nested Keys

Translation file:

{
  "menu": {
    "home": "Home"
  }
}

Usage:

this.translate.instant('menu.home');

Template:

{{ 'menu.home' | baherTranslate }}

Result:

Home

API Reference

provideBaherTranslate

Registers the translation provider and configuration.

provideBaherTranslate({
  defaultLanguage: 'en',
  supportedLanguages: ['en', 'ar'],
  loaderPath: 'public/i18n/'
});

BaherTranslateService

Main translation service.

setLanguage

setLanguage(language: string): void

Changes the active application language.

Example:

this.translate.setLanguage('ar');

instant

instant(key: string): string

Returns the translated value immediately.

Example:

this.translate.instant('app.title');

BaherTranslatePipe

Used to translate keys directly inside Angular templates.

{{ 'app.title' | baherTranslate }}

Configuration Interface

export interface BaherTranslateConfig {
  defaultLanguage: string;
  supportedLanguages: string[];
  loaderPath?: string;
}

NX Commands

Build

nx build translate

Lint

nx lint translate

Production Build

nx build translate --configuration production

Folder Structure

translate/
├── docs/
│   └── images/
│       └── logo.png
├── src/
│   ├── lib/
│   │   ├── interfaces/
│   │   ├── pipes/
│   │   ├── providers/
│   │   ├── services/
│   │   ├── tokens/
│   │   └── types/
│   ├── index.ts
│   └── public-api.ts
├── eslint.config.mjs
├── ng-package.json
├── package.json
├── project.json
├── README.md
├── tsconfig.json
├── tsconfig.lib.json
└── tsconfig.lib.prod.json

Author & Contact

Baher Hamed

For permission requests, please contact:

Email: [email protected]

License

This project is proprietary software.

All rights reserved.

No permission is granted to use, copy, modify, distribute, publish, sublicense, sell, reuse, or create derivative works from any part of this software without explicit prior written permission from the author.

See the root LICENSE file for more details.

🇸🇦 التوثيق العربي

نظرة عامة

baher-translate هي مكتبة ترجمة خفيفة تم تطويرها لتطبيقات Angular الحديثة.

تعتمد المكتبة داخليًا على Angular Signals وتوفر واجهة بسيطة لإدارة اللغات وتحميل ملفات الترجمة وتغيير اللغة أثناء تشغيل التطبيق.

تم اختبار المكتبة بنجاح مع:

• Angular 20
• تطبيقات CSR
• تطبيقات SSR
• NX Workspace
• تطبيقات Angular Standalone

المميزات

• دعم Angular Signals
• متوافقة مع Angular 20
• تدعم SSR
• تدعم CSR
• تدعم Standalone Components
• تغيير اللغة أثناء التشغيل
• إمكانية تخصيص مسار ملفات الترجمة
• دعم مفاتيح الترجمة المتداخلة
• خفيفة وسهلة الاستخدام
• دعم TypeScript
• سهلة الدمج مع Dependency Injection
• مناسبة لمشاريع NX Monorepo
• لا تعتمد على مكتبات ترجمة خارجية

التثبيت

npm install baher-translate

هيكل ملفات الترجمة

مثال:

public/
└── i18n/
    ├── en.json
    └── ar.json

مثال ملفات الترجمة

en.json

{
  "app": {
    "title": "Baher Application",
    "description": "Modern Angular application"
  },
  "menu": {
    "home": "Home",
    "about": "About",
    "contact": "Contact"
  }
}

ar.json

{
  "app": {
    "title": "تطبيق باهر",
    "description": "تطبيق Angular حديث"
  },
  "menu": {
    "home": "الرئيسية",
    "about": "من نحن",
    "contact": "تواصل معنا"
  }
}

الإعداد

app.config.ts

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideBaherTranslate } from 'baher-translate';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),

    provideBaherTranslate({
      defaultLanguage: 'en',
      supportedLanguages: ['en', 'ar'],
      loaderPath: 'public/i18n/'
    })
  ]
};

استخدام الخدمة

import { Component, inject } from '@angular/core';
import { BaherTranslateService } from 'baher-translate';

@Component({
  selector: 'app-root',
  standalone: true,
  template: `
    <h1>{{ title() }}</h1>

    <button type="button" (click)="changeLanguage('en')">
      English
    </button>

    <button type="button" (click)="changeLanguage('ar')">
      العربية
    </button>
  `
})
export class AppComponent {
  private readonly translate = inject(BaherTranslateService);

  title = () => this.translate.instant('app.title');

  changeLanguage(language: string): void {
    this.translate.setLanguage(language);
  }
}

استخدام Pipe

استيراد Pipe

import { BaherTranslatePipe } from 'baher-translate';

مثال داخل Component

import { Component } from '@angular/core';
import { BaherTranslatePipe } from 'baher-translate';

@Component({
  selector: 'app-home',
  standalone: true,
  imports: [BaherTranslatePipe],
  template: `
    <h1>{{ 'app.title' | baherTranslate }}</h1>
    <p>{{ 'app.description' | baherTranslate }}</p>
  `
})
export class HomeComponent {}

المفاتيح المتداخلة

ملف الترجمة:

{
  "menu": {
    "home": "Home"
  }
}

الاستخدام داخل TypeScript:

this.translate.instant('menu.home');

الاستخدام داخل HTML:

{{ 'menu.home' | baherTranslate }}

النتيجة:

Home

مرجع الاستخدام

provideBaherTranslate

تستخدم لتسجيل إعدادات ومزودي الترجمة داخل التطبيق.

provideBaherTranslate({
  defaultLanguage: 'en',
  supportedLanguages: ['en', 'ar'],
  loaderPath: 'public/i18n/'
});

BaherTranslateService

الخدمة الأساسية الخاصة بالترجمة.

setLanguage

setLanguage(language: string): void

تستخدم لتغيير اللغة الحالية للتطبيق.

مثال:

this.translate.setLanguage('ar');

instant

instant(key: string): string

تستخدم للحصول على قيمة الترجمة مباشرة.

مثال:

this.translate.instant('app.title');

BaherTranslatePipe

تستخدم لترجمة المفاتيح مباشرة داخل قوالب Angular.

{{ 'app.title' | baherTranslate }}

واجهة الإعدادات

export interface BaherTranslateConfig {
  defaultLanguage: string;
  supportedLanguages: string[];
  loaderPath?: string;
}

أوامر NX

بناء المكتبة

nx build translate

فحص الكود

nx lint translate

بناء نسخة الإنتاج

nx build translate --configuration production

هيكل المكتبة

translate/
├── docs/
│   └── images/
│       └── logo.png
├── src/
│   ├── lib/
│   │   ├── interfaces/
│   │   ├── pipes/
│   │   ├── providers/
│   │   ├── services/
│   │   ├── tokens/
│   │   └── types/
│   ├── index.ts
│   └── public-api.ts
├── eslint.config.mjs
├── ng-package.json
├── package.json
├── project.json
├── README.md
├── tsconfig.json
├── tsconfig.lib.json
└── tsconfig.lib.prod.json

المؤلف والتواصل

Baher Hamed

لطلب إذن استخدام أو أي استفسار متعلق بالمستودع:

Email: [email protected]

License

This project is licensed under the MIT License.

See the root LICENSE file for details.

الترخيص

هذا المشروع مرخص تحت ترخيص MIT.

راجع ملف LICENSE الموجود في جذر المشروع لمزيد من التفاصيل.