I18nProvider

This file defines the I18nProvider class, which offers internationalization (i18n) utilities for the @sodacore/core framework. It provides methods for translating strings, auto-translating objects and arrays, parsing translation tags, and negotiating the best language based on the client's Accept-Language header.

---

Features

• String Translation: Translates individual keys or phrases using the current or specified language.
• Automatic Deep Translation: Recursively translates all strings within objects or arrays, preserving the original structure.
• Translation Tag Parsing: Supports translation tags within strings for partial or inline translation.
• Language Negotiation: Selects the best available language based on the Accept-Language HTTP header and available translations.
• Fallback Handling: Returns fallback values if translations are unavailable.

---

Usage

import I18nProvider from './provider/i18n';

const i18n = new I18nProvider();

// Translate a string
const greeting = i18n.t('hello.world', 'fr');

// Auto-translate an object
const translatedData = i18n.autoTranslate({ title: 'hello.world', desc: 'welcome' }, 'es');

// Get the best available language from an Accept-Language header
const lang = i18n.getAvailableTranslation('en-US,en;q=0.9,fr;q=0.8');

---

API

t(query: string, languageCode: string, fallback?: string): string

Translates a string using the specified language code, with an optional fallback.

translate(query: string, languageCode: string, fallback?: string): string

Translates a string using the I18nService. Returns the fallback or original query if no translation is found.

autoTranslate(data: string | Array<any> | Record<string, any>, languageCode: string): any

Recursively translates all strings within the provided data (string, array, or object) using the specified language code.

autoTranslateText(query: string, languageCode: string): string

Translates all translation tags within a string using the specified language code.

getTranslateMatches(query: string): Array<{ token: string, inner: string }>

Finds all translation tags in a string and returns their tokens and full matches.

getAvailableTranslation(acceptedLanguages: string): string | null

Determines the best available language based on the Accept-Language header and available translations. Returns the language code or null if no suitable match is found.

---

How It Works

1. Translation:

   • Uses the I18nService to look up translations for a given query and language code.
   • If no translation is found, returns the fallback or the original string.

2. Auto-Translation:

   • Deep clones the input data to avoid mutation.
   • Recursively traverses objects and arrays, translating all string values using autoTranslateText.

3. Translation Tags:

   • Searches for translation tags in strings using regular expressions.
   • Replaces each tag with its translated value.

4. Language Negotiation:

   • Parses the Accept-Language header to determine preferred languages and priorities.
   • Selects the best match from available translations, considering the default language.

---

Notes

• Translation tags must match the REGEX_TRANSLATION_TAG pattern to be detected and replaced.
• The provider relies on I18nService for actual translation data and available languages.
• The defaultLanguage is determined from the configuration if provided.
• Designed for use in both HTTP and application-level internationalization scenarios.