npm package: @nettyapps/ntyi18n
Description: The i18n library provides a comprehensive solution for managing multi-language support in Angular applications. Built on top of `@ngx-translate/core`, it offers advanced functionality for language management, translation merging, and persistent language p
Latest version: 21.1.0

# Netty i18n Library

The i18n library provides a comprehensive solution for managing multi-language support in Angular applications. Built on top of `@ngx-translate/core`, it offers advanced functionality for language management, translation merging, and persistent language preferences.

**Key Features:**

- **Language persistence:** Remembers user language preference via localStorage
- **Translation merging:** Ability to merge with existing translations or overwrite them
- **Multi-language support:** Easy to add new languages
- **Browser language detection:** Automatically detects browser/OS language
- **API language codes:** Maintains separate API language codes for backend communication

## Installation

To add the ntyi18n library to your project, use the following command:

```bash
npm install @nettyapps/ntyi18n
```

Ensure `@ngx-translate/core` is installed as a dependency.

## I18nService Usage

### Initialization

Initialize the service in your root component (typically `app.ts`):

```typescript
import { I18nService } from "@nettyapps/ntyi18n";

@Component({
  // ...
})
export class AppComponent implements OnInit {
  constructor(private i18nService: I18nService) {}

  ngOnInit() {
    this.i18nService.init(environment.defaultLanguage, environment.supportedLanguages);
  }
}
```

### Changing Language

To programmatically change the current language:

```typescript
this.i18nService.language = "Français";
```

### Getting Current Language

To get the current language:

```typescript
const currentLang = this.i18nService.language;
```

## Adding New Languages

The library includes English (en-US) and Turkish (tr-TR) translations by default. In your main project:

1. You can override these translations
2. Add new languages
3. Merge with new translations

### Step 1: Create Translation File

Create a JSON file for your new language in the `assets/i18n/` folder (e.g., `fr-FR.json` for French).

Use the same structure as existing translation files (`en-US.json` and `tr-TR.json`).

```json
{
  "common": {
    "welcome": "Bienvenue",
    "save": "Enregistrer"
  }
}
```

### Step 2: Update Environment Configuration

Update the `environment.ts` file to include the new language:

```typescript
export const environment = {
  production: false,
  version: env["npm_package_version"],
  defaultLanguage: "Türkçe", // Default language
  supportedLanguages: ["Türkçe", "English", "Français"], // New language
};
```

### Step 3: Register Translation with Application

During application initialization (typically in `app.ts`):

```typescript
import frFR from "../assets/i18n/fr-FR.json";

constructor(private i18nService: I18nService) {
  this.i18nService.addTranslations("Français", frFR, true);
}
```

### Dynamic Translation Merging

The `addTranslations` method allows you to dynamically add or update translations:

```typescript
/**
 * Adds new translations or updates existing ones
 * @param lang Language code (e.g., 'English', 'Türkçe')
 * @param translations Translation JSON object
 * @param shouldMerge If true, merges with existing translations; if false, overwrites
 */
this.i18nService.addTranslations("Türkçe", trTR, true);
```

- **Merge (true):** Combines new translations with existing ones, preserving existing keys not present in new translations

- **Overwrite (false):** Completely replaces all translations for the specified language