feat(interpolation): improve docs

antimprisacaru · Sep 22, 2024 · eb5ecf9 · eb5ecf9
1 parent dbc9ed2
commit eb5ecf9
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 134 deletions.
diff --git a/README.md b/README.md
@@ -1,30 +1,18 @@
-# ng-intl
+# Angular Internationalization
 
-## Revolutionize Your Angular Translations
+## Type-Safe and Reactive Translations for Angular
 
-Tired of juggling translation keys and hunting down typos? Say hello to ng-intl – the game-changing Angular translation library that brings the power of intellisense to your i18n workflow.
+ng-intl revolutionizes Angular internationalization with type-safety, IDE intellisense, and signal-based reactivity.
 
-🚀 **First of Its Kind**: Harness the full potential of your IDE with unparalleled intellisense support for translations.
+🚀 **Efficient**: Lazy-load bundled translations without HTTP requests.
 
-🔧 **Type-Safe & Flexible**: Catch errors before they happen and adapt to your project's needs with ease.
+🔍 **Type-Safe**: Full TypeScript and IDE intellisense support.
 
-🌐 **JSON & TypeScript Ready**: Whether you prefer JSON simplicity or TypeScript sophistication, we've got you covered.
+⚡ **Reactive**: Signal-based for seamless language switching.
 
-💡 **Smart Interpolation**: Seamlessly integrate dynamic content into your translations.
+🔧 **Flexible**: Supports both JSON and TypeScript translation files.
 
-⚡ **Lightning-Fast Setup**: Get up and running in minutes, not hours.
-
-ng-intl isn't just another translation library – it's your partner in creating truly global Angular applications. Dive in and experience the future of Angular internationalization!
-
-## Features
-
-- Groundbreaking intellisense support for translations
-- Dynamic loading of translations for optimal performance
-- Seamless support for both JSON and TypeScript (.ts) translation files
-- Rock-solid type safety for translation keys
-- Clever interpolation support for dynamic content
-- Highly configurable language settings
-- Intuitive service for effortless translation management
+🌐 **Scalable**: Ideal for projects of all sizes.
 
 ## Installation
 
@@ -34,54 +22,39 @@ npm install @ng-intl/core
 
 ## Quick Start
 
-1. Provide the translation service and configuration in your app module or in the `providers` array of your `main.ts`:
+1. Configure the translation service:
 
 ```typescript
 import { provideTranslation } from '@ng-intl/core';
 
-// ...
-
 providers: [
-  provideTranslation() // Uses default configuration
-  // Or customize the configuration:
-  // provideTranslation({
-  //   defaultLanguage: 'en',
-  //   interpolation: 'brackets'
-  // })
+  provideTranslation({ defaultLanguage: 'en' })
 ]
 ```
 
-2. Add the languages and use the translation service in your component:
+2. Set up your translations:
 
 ```typescript
 import { createScopedTranslation, LanguageService } from '@ng-intl/core';
 
 const { TranslationService, provideScopedTranslation } = createScopedTranslation({
   en: () => import('./i18n/en.json'),
-  es: () => import('./i18n/es'),  // Note: supports both .json and .ts files
+  es: () => import('./i18n/es'),
   fr: () => import('./i18n/fr.json')
 });
 ```
 
-3. Provide the scoped translation via `provideScopedTranslation()` output, and you can inject the service in your component.
-   This will let you use the scoped translation service.
+3. Use in your component:
 
 ```typescript
 @Component({
   selector: 'app-root',
   template: `
-    <header>
-      <h1>{{ translations()?.appTitle }}</h1>
-      <nav>
-        <button (click)="changeLanguage('en')">English</button>
-        <button (click)="changeLanguage('es')">Español</button>
-        <button (click)="changeLanguage('fr')">Français</button>
-      </nav>
-    </header>
-    <main>
-      <p>{{ translations()?.welcomeMessage | interpolate: { username: currentUser } }}</p>
-      <p>{{ translations()?.currentLanguage }}: {{ currentLanguage }}</p>
-    </main>
+    <h1>{{ translations()?.appTitle }}</h1>
+    <p>{{ translations()?.welcomeMessage | interpolate: { username: currentUser } }}</p>
+    <button (click)="changeLanguage('en')">{{ translations()?.languages.english }}</button>
+    <button (click)="changeLanguage('es')">{{ translations()?.languages.spanish }}</button>
+    <button (click)="changeLanguage('fr')">{{ translations()?.languages.french }}</button>
   `,
   providers: [provideScopedTranslation()]
 })
@@ -90,43 +63,38 @@ export class AppComponent {
   private readonly languageService = inject(LanguageService);
 
   currentUser = 'John Doe';
-  currentLanguage = 'en';
 
   protected changeLanguage(lang: 'en' | 'es' | 'fr') {
     this.languageService.setLanguage(lang);
   }
 }
-
 ```
 
-## Configuration
+## Features
 
-The `provideTranslation()` function sets up the translation configuration. It can be used without arguments to use the default configuration:
+- **Lazy Loading**: Translations are bundled but loaded on-demand, optimizing performance without extra HTTP requests.
+- **Signal-Based Reactivity**: Translations use Angular signals for perfect reactivity on language changes.
+- **Intellisense Support**: Enjoy unparalleled IDE support with autocompletion and type checking for translation keys.
+- **Dynamic Language Switching**: Easily switch languages at runtime with built-in language management.
+- **Powerful Interpolation**: Handle complex scenarios with variable interpolation, pluralization, and conditional content.
+- **Scoped Translations**: Organize translations efficiently with scoped services for different parts of your application.
 
-```typescript
-import { provideTranslation } from '@ng-intl/core';
+## InterpolationPipe
 
-providers: [
-  provideTranslation() // Uses default configuration
-]
-```
+The `InterpolationPipe` offers versatile string interpolation and localization:
 
-Or you can customize the configuration:
+```html
+<!-- Simple interpolation -->
+{{ 'Hello, {{name}}!' | interpolate:{ name: 'World' } }}
 
-```typescript
-import { provideTranslation } from '@ng-intl/core';
+<!-- Select rule -->
+{{ 'mySelectRule: "{gender, select, male {He} female {She} other {They}}"' | interpolate:{ gender: 'female' } }}
 
-providers: [
-  provideTranslation({
-    defaultLanguage: 'en',
-    interpolation: 'brackets' // or 'parentheses'
-  })
-]
+<!-- Plural rule -->
+{{ 'myPluralRule: "{count, plural, =0 {no results} one {1 result} other {# results}}"' | interpolate:{ count: 5 } }}
 ```
 
-Default configuration:
-- `defaultLanguage: 'en'`
-- `interpolation: 'brackets'`
+The pipe supports nested rules, whitespace handling, fallbacks, and various data types, making it suitable for complex internationalization scenarios.
 
 ## License
 

diff --git a/packages/core/README.md b/packages/core/README.md
@@ -1,30 +1,18 @@
-# ng-intl
+# Angular Internationalization
 
-## Revolutionize Your Angular Translations
+## Type-Safe and Reactive Translations for Angular
 
-Tired of juggling translation keys and hunting down typos? Say hello to ng-intl – the game-changing Angular translation library that brings the power of intellisense to your i18n workflow.
+ng-intl revolutionizes Angular internationalization with type-safety, IDE intellisense, and signal-based reactivity.
 
-🚀 **First of Its Kind**: Harness the full potential of your IDE with unparalleled intellisense support for translations.
+🚀 **Efficient**: Lazy-load bundled translations without HTTP requests.
 
-🔧 **Type-Safe & Flexible**: Catch errors before they happen and adapt to your project's needs with ease.
+🔍 **Type-Safe**: Full TypeScript and IDE intellisense support.
 
-🌐 **JSON & TypeScript Ready**: Whether you prefer JSON simplicity or TypeScript sophistication, we've got you covered.
+⚡ **Reactive**: Signal-based for seamless language switching.
 
-💡 **Smart Interpolation**: Seamlessly integrate dynamic content into your translations.
+🔧 **Flexible**: Supports both JSON and TypeScript translation files.
 
-⚡ **Lightning-Fast Setup**: Get up and running in minutes, not hours.
-
-ng-intl isn't just another translation library – it's your partner in creating truly global Angular applications. Dive in and experience the future of Angular internationalization!
-
-## Features
-
-- Groundbreaking intellisense support for translations
-- Dynamic loading of translations for optimal performance
-- Seamless support for both JSON and TypeScript (.ts) translation files
-- Rock-solid type safety for translation keys
-- Clever interpolation support for dynamic content
-- Highly configurable language settings
-- Intuitive service for effortless translation management
+🌐 **Scalable**: Ideal for projects of all sizes.
 
 ## Installation
 
@@ -34,54 +22,39 @@ npm install @ng-intl/core
 
 ## Quick Start
 
-1. Provide the translation service and configuration in your app module or in the `providers` array of your `main.ts`:
+1. Configure the translation service:
 
 ```typescript
 import { provideTranslation } from '@ng-intl/core';
 
-// ...
-
 providers: [
-  provideTranslation() // Uses default configuration
-  // Or customize the configuration:
-  // provideTranslation({
-  //   defaultLanguage: 'en',
-  //   interpolation: 'brackets'
-  // })
+  provideTranslation({ defaultLanguage: 'en' })
 ]
 ```
 
-2. Add the languages and use the translation service in your component:
+2. Set up your translations:
 
 ```typescript
 import { createScopedTranslation, LanguageService } from '@ng-intl/core';
 
 const { TranslationService, provideScopedTranslation } = createScopedTranslation({
   en: () => import('./i18n/en.json'),
-  es: () => import('./i18n/es'),  // Note: supports both .json and .ts files
+  es: () => import('./i18n/es'),
   fr: () => import('./i18n/fr.json')
 });
 ```
 
-3. Provide the scoped translation via `provideScopedTranslation()` output, and you can inject the service in your component. 
-This will let you use the scoped translation service. 
+3. Use in your component:
 
 ```typescript
 @Component({
   selector: 'app-root',
   template: `
-    <header>
-      <h1>{{ translations()?.appTitle }}</h1>
-      <nav>
-        <button (click)="changeLanguage('en')">English</button>
-        <button (click)="changeLanguage('es')">Español</button>
-        <button (click)="changeLanguage('fr')">Français</button>
-      </nav>
-    </header>
-    <main>
-      <p>{{ translations()?.welcomeMessage | interpolate: { username: currentUser } }}</p>
-      <p>{{ translations()?.currentLanguage }}: {{ currentLanguage }}</p>
-    </main>
+    <h1>{{ translations()?.appTitle }}</h1>
+    <p>{{ translations()?.welcomeMessage | interpolate: { username: currentUser } }}</p>
+    <button (click)="changeLanguage('en')">{{ translations()?.languages.english }}</button>
+    <button (click)="changeLanguage('es')">{{ translations()?.languages.spanish }}</button>
+    <button (click)="changeLanguage('fr')">{{ translations()?.languages.french }}</button>
   `,
   providers: [provideScopedTranslation()]
 })
@@ -90,43 +63,38 @@ export class AppComponent {
   private readonly languageService = inject(LanguageService);
 
   currentUser = 'John Doe';
-  currentLanguage = 'en';
 
   protected changeLanguage(lang: 'en' | 'es' | 'fr') {
     this.languageService.setLanguage(lang);
   }
 }
-
 ```
 
-## Configuration
+## Features
 
-The `provideTranslation()` function sets up the translation configuration. It can be used without arguments to use the default configuration:
+- **Lazy Loading**: Translations are bundled but loaded on-demand, optimizing performance without extra HTTP requests.
+- **Signal-Based Reactivity**: Translations use Angular signals for perfect reactivity on language changes.
+- **Intellisense Support**: Enjoy unparalleled IDE support with autocompletion and type checking for translation keys.
+- **Dynamic Language Switching**: Easily switch languages at runtime with built-in language management.
+- **Powerful Interpolation**: Handle complex scenarios with variable interpolation, pluralization, and conditional content.
+- **Scoped Translations**: Organize translations efficiently with scoped services for different parts of your application.
 
-```typescript
-import { provideTranslation } from '@ng-intl/core';
+## InterpolationPipe
 
-providers: [
-  provideTranslation() // Uses default configuration
-]
-```
+The `InterpolationPipe` offers versatile string interpolation and localization:
 
-Or you can customize the configuration:
+```html
+<!-- Simple interpolation -->
+{{ 'Hello, {{name}}!' | interpolate:{ name: 'World' } }}
 
-```typescript
-import { provideTranslation } from '@ng-intl/core';
+<!-- Select rule -->
+{{ 'mySelectRule: "{gender, select, male {He} female {She} other {They}}"' | interpolate:{ gender: 'female' } }}
 
-providers: [
-  provideTranslation({
-    defaultLanguage: 'en',
-    interpolation: 'brackets' // or 'parentheses'
-  })
-]
+<!-- Plural rule -->
+{{ 'myPluralRule: "{count, plural, =0 {no results} one {1 result} other {# results}}"' | interpolate:{ count: 5 } }}
 ```
 
-Default configuration:
-- `defaultLanguage: 'en'`
-- `interpolation: 'brackets'`
+The pipe supports nested rules, whitespace handling, fallbacks, and various data types, making it suitable for complex internationalization scenarios.
 
 ## License