/** * Configuration passed to . * This is the main setup developers do when integrating BhashaJS. */ interface BhashaConfig { /** * Your project ID from the BhashaJS dashboard. * Required when using apiToken (JWT) auth. * Not needed when using projectKey. */ projectId?: string; /** * Your project API key (starts with "bjs_"). * Get this from Project Settings → API Key in the dashboard. * This is the recommended auth method for client-side apps. * Uses public /api/sdk/* endpoints — no JWT needed. */ projectKey?: string; /** * The language to show by default when the app loads. * Should be one of your project's supported languages. * @default "en" */ defaultLang?: string; /** * The base URL of your BhashaJS API. * Only change this if you self-host the backend. * @default "https://api.bhashajs.com/api" */ apiUrl?: string; /** * Your API authentication token. * Get this from the BhashaJS dashboard under project settings. */ apiToken?: string; /** * Preloaded translations — skip the API call entirely. * Useful for SSR or if you bundle translations with your app. * Format: { "en": { "hero.title": "Welcome" }, "hi": { "hero.title": "स्वागत" } } */ preloadedTranslations?: Record>; /** * Persist fetched text bundles in localStorage for offline/first-paint reuse. * The SDK serves the cached bundle immediately, then refreshes in the background. * @default true */ persistCache?: boolean; /** * Called whenever the language changes. * Useful for analytics, saving preference to localStorage, etc. */ onLanguageChange?: (lang: string) => void; /** * Region override (e.g. "IN", "BD", "PK", "LK", "NP"). * Overrides the default region for the current language. * This affects currency formatting and Intl locale selection. * * Example: Bengali in Bangladesh uses ৳ (Taka), but Bengali in India uses ₹ (Rupee). * Set region="IN" to use Indian formatting for Bengali speakers in India. */ region?: string; /** * The register (formality / style) to render translations at. * * - "default" (default) — neutral conversational tone * - "formal" — high-formality, honorific, native-vocabulary * preferred. Good for legal, banking, gov, insurance. * - "casual" — Gen-Z friendly, code-mixing with English encouraged * where natural. Good for consumer, marketing, chat. * * If a string is missing in the requested register, the SDK falls back to * "default" before falling back through language chains. */ register?: Register; /** * If true, also fetch the voice bundle (IPA + SSML) on init so * `formatPhonetic()` and `formatSSML()` return non-empty strings. * * Default: false. Most apps don't need voice data, so we don't pay the * extra round-trip unless explicitly requested. */ voice?: boolean; /** * Initial user segment label (free-form, e.g. "genz", "enterprise", "default"). * When combined with `segmentRules`, the segment selects the active register * automatically — same `t("hero.cta")` returns different copy per segment * with no app-level branching. * * Switch at runtime via `setSegment()` from `useTranslation()`. */ userSegment?: string; /** * Map of segment label → register. When `userSegment` matches a key here, * the SDK uses that register as the active one (overriding `register`). * If the segment isn't in the map, the SDK falls back to `register` or * to `"default"`. * * Example: * segmentRules={{ genz: "casual", enterprise: "formal" }} */ segmentRules?: Record; } /** * Register = formality / style of a translation. */ type Register = "default" | "formal" | "casual"; /** * Augmentable registry of a project's translation keys. * * Empty by default — so `BhashaKey` falls back to `string` and nothing breaks. * The `bhasha pull` CLI generates a declaration file that augments this with * your real keys, turning `t()` / `` into type-safe, autocompleted, * typo-proof calls: * * // bhasha-keys.d.ts (generated — do not edit) * declare module "bhasha-js" { * interface BhashaKeyRegistry { * "hero.title": string; * "greeting": string; * } * } */ interface BhashaKeyRegistry { } /** * The type of a valid translation key. When the registry is empty this is * `string` (zero friction); once `bhasha pull` has populated the registry it * narrows to the exact union of your keys, so a typo is a compile error. * * The `[…] extends […]` tuple wrap is deliberate: it stops the conditional * from distributing over `never`, so the empty-registry case resolves to * `string` rather than collapsing to `never`. */ type BhashaKey = [keyof BhashaKeyRegistry] extends [never] ? string : keyof BhashaKeyRegistry; /** * Information about a supported language. * Used internally for display names, fonts, direction, formatting, etc. */ interface LangInfo { /** Language code (e.g. "hi") */ code: string; /** Display name in the language's own script (e.g. "हिन्दी") */ name: string; /** Display name in English (e.g. "Hindi") */ englishName: string; /** Text direction */ dir: "ltr" | "rtl"; /** Recommended Google Font for this script */ font: string; /** Script name (e.g. "Devanagari", "Bengali", "Nastaliq") */ script: string; /** Default region/country code (e.g. "IN", "BD", "PK") */ defaultRegion: string; /** Intl locale string for formatting (e.g. "hi-IN", "bn-BD") */ intlLocale: string; /** Unicode numbering system for native digits (e.g. "deva", "beng", "tamldec") */ numberingSystem: string; /** Default currency code (e.g. "INR", "BDT", "PKR") */ defaultCurrency: string; } /** * Options for formatNumber(). */ interface NumberFormatOptions { /** Render digits in the native script (e.g. १२३ instead of 123) */ useNativeDigits?: boolean; /** Use compact notation (e.g. "1.5L", "2Cr") */ compact?: boolean; } /** * Options for formatCurrency(). */ interface CurrencyFormatOptions { /** Override the auto-detected currency code (e.g. "INR", "BDT", "PKR") */ currency?: string; /** How to display the currency: symbol (₹), code (INR), or name (Indian rupees) */ display?: "symbol" | "code" | "name"; /** Render digits in the native script */ useNativeDigits?: boolean; } /** * Options for formatDate(). */ interface DateFormatOptions { /** * Formatting preset: * - "short": 19/03/26 * - "medium": 19 Mar 2026 * - "long": 19 March 2026 * - "full": Thursday, 19 March 2026 * @default "medium" */ preset?: "short" | "medium" | "long" | "full"; /** Render digits in the native script */ useNativeDigits?: boolean; } /** * Built-in language database — 14 entries covering 13 languages. * (Punjabi has two entries: Gurmukhi for India, Shahmukhi for Pakistan) * * Every South Asian language we support has: * - Its name in its own script (so the switcher shows हिन्दी not "Hindi") * - Text direction (RTL for Urdu/Shahmukhi Punjabi) * - A recommended Google Font that properly renders the script * - Default region, locale, currency, and numbering system for formatting */ declare const LANGUAGES: Record; /** * Region overrides for languages that span multiple countries. * * Some languages are spoken across borders with different currencies: * - Bengali: Bangladesh (৳ Taka) vs India (₹ Rupee) * - Tamil: India (₹ Rupee) vs Sri Lanka (Rs) * - Urdu: Pakistan (Rs) vs India (₹ Rupee) * * Developers pass region="IN" to to override defaults. * The key format is "{langCode}-{regionCode}". */ declare const REGION_OVERRIDES: Record; /** * Get language info. Returns a default for unknown languages * so the SDK never crashes on an unrecognized code. */ declare function getLangInfo(code: string): LangInfo; /** * Get the fallback chain for a language. * If no custom chain exists, defaults to [lang, "en"]. */ declare function getFallbackChain(lang: string): string[]; /** * Resolve the effective locale and currency for a language + optional region. * Checks REGION_OVERRIDES first, then falls back to the language's defaults. */ declare function resolveRegion(lang: string, region?: string): { intlLocale: string; currency: string; }; /** * Format a number using South Asian conventions. * * Uses lakh/crore grouping automatically for South Asian locales. * Supports native digit rendering and compact notation. * * @param value - The number to format * @param lang - Language code (e.g. "hi", "bn") * @param region - Optional region override (e.g. "IN", "BD") * @param options - Formatting options * * @example * formatNumber(1234567, "hi") // → "12,34,567" * formatNumber(1234567, "hi", undefined, { useNativeDigits: true }) // → "१२,३४,५६७" * formatNumber(1234567, "en") // → "12,34,567" (en-IN uses lakh/crore) * formatNumber(1500000, "hi", undefined, { compact: true }) // → "15 लाख" */ declare function formatNumber(value: number, lang: string, region?: string, options?: NumberFormatOptions): string; /** * Format a currency value with region-aware symbol and lakh/crore grouping. * * Auto-detects the correct currency from the language and region: * - Hindi (IN) → ₹ Bengali (BD) → ৳ Urdu (PK) → Rs * - Bengali (IN) → ₹ (with region override) * * @param value - The amount to format * @param lang - Language code (e.g. "hi", "bn") * @param region - Optional region override * @param options - Formatting options * * @example * formatCurrency(1234567, "hi") // → "₹12,34,567.00" * formatCurrency(1234567, "bn") // → "৳12,34,567.00" (Bangladesh default) * formatCurrency(1234567, "bn", "IN") // → "₹12,34,567.00" (India override) * formatCurrency(1234567, "hi", undefined, { display: "code" }) // → "INR 12,34,567.00" */ declare function formatCurrency(value: number, lang: string, region?: string, options?: CurrencyFormatOptions): string; /** * Format a date using South Asian conventions. * * Defaults to DD/MM/YYYY (not the American MM/DD/YYYY). * Supports four presets and native digit rendering. * * @param date - Date to format (Date object, ISO string, or timestamp) * @param lang - Language code * @param region - Optional region override * @param options - Formatting options * * @example * formatDate(new Date("2026-03-19"), "hi") // → "19 मार्च 2026" * formatDate(new Date("2026-03-19"), "hi", undefined, { preset: "short" }) // → "19/3/26" * formatDate(new Date("2026-03-19"), "hi", undefined, { preset: "full" }) // → "गुरुवार, 19 मार्च 2026" * formatDate(new Date("2026-03-19"), "hi", undefined, { useNativeDigits: true }) // → "१९ मार्च २०२६" */ declare function formatDate(date: Date | string | number, lang: string, region?: string, options?: DateFormatOptions): string; /** * Get the CLDR plural category for a number in a given language. * * @param count - The number to pluralize (e.g. 0, 1, 5) * @param lang - The language code (e.g. "hi", "en") * @returns "one" (singular) or "other" (plural) * * @example * getPluralCategory(0, "en") // → "other" (English: "0 items") * getPluralCategory(0, "hi") // → "one" (Hindi: "0 आइटम") * getPluralCategory(1, "en") // → "one" (English: "1 item") * getPluralCategory(1, "hi") // → "one" (Hindi: "1 आइटम") * getPluralCategory(5, "en") // → "other" (English: "5 items") * getPluralCategory(5, "hi") // → "other" (Hindi: "5 आइटमें") */ declare function getPluralCategory(count: number, lang: string): "one" | "other"; export { type BhashaConfig as B, type CurrencyFormatOptions as C, type DateFormatOptions as D, LANGUAGES as L, type NumberFormatOptions as N, type Register as R, type BhashaKey as a, type BhashaKeyRegistry as b, type LangInfo as c, REGION_OVERRIDES as d, formatDate as e, formatCurrency as f, formatNumber as g, getFallbackChain as h, getLangInfo as i, getPluralCategory as j, resolveRegion as r };