@better-i18n/core 0.3.0 → 0.5.0

package/README.md

@@ -8,7 +8,7 @@ Framework-agnostic core utilities for fetching translations from Better i18n CDN
 - **Edge-Ready** - Optimized for edge environments (Cloudflare, Vercel, etc.)
 - **Type-Safe** - Full TypeScript support
 - **Cached** - Built-in manifest caching with configurable TTL
-- **Offline Fallback** - 3-tier fallback chain: CDN → persistent storage → static data
+- **Offline Fallback** - 5-layer fallback chain: TtlCache → CDN (with ETag 304) → persistent storage → static data
 - **Resilient** - Configurable fetch timeout and retry with exponential backoff
 
 ## Installation
@@ -69,12 +69,18 @@ interface I18nCoreConfig {
 
 ## Offline Fallback
 
-When CDN is unavailable, translations are resolved through a 3-tier fallback chain:
+Translations are resolved through a 5-layer fallback chain:
 
 ```
-CDN (primary) → Storage (persistent cache) → Static Data (bundled) → throw
+TtlCache (in-memory) → CDN fetch → CDN 304 (ETag) → Storage (persistent cache) → Static Data (bundled) → throw
 ```
 
+1. **TtlCache** — In-memory cache with configurable TTL (default: 5 minutes). Instant, no I/O.
+2. **CDN fetch** — Fresh translation data from Better i18n CDN.
+3. **CDN 304 (ETag)** — If CDN returns "not modified", reuse cached version.
+4. **Storage** — Persistent cache (localStorage, AsyncStorage, etc.) survives app restarts.
+5. **Static Data** — Bundled translations as absolute last resort.
+
 ### Storage Adapter
 
 Persist translations locally so they survive CDN outages and app restarts:

package/dist/i18n/detection.d.ts

@@ -1,6 +1,49 @@
 import type { LocaleDetectionOptions, LocaleDetectionResult } from "./types.js";
+import type { LanguageOption } from "../types.js";
 /**
- * Framework-agnostic locale detection logic
+ * Build a country→locale map from CDN manifest languages.
+ *
+ * Uses each language's `countryCode` field as the primary source
+ * (set in the Better i18n dashboard). Falls back to `LANGUAGE_TO_COUNTRY`
+ * reverse lookup for languages without explicit country codes.
+ *
+ * Also includes multi-country overrides (e.g. AT→de, MX→es) so that
+ * visitors from countries sharing a language are correctly mapped.
+ *
+ * @example
+ * ```ts
+ * const languages = await i18n.getLanguages();
+ * const countryMap = buildCountryLocaleMap(languages);
+ * // { tr: "tr", de: "de", jp: "ja", cn: "zh-hans", at: "de", mx: "es", ... }
+ * ```
+ */
+export declare function buildCountryLocaleMap(languages: LanguageOption[]): Record<string, string>;
+/**
+ * Framework-agnostic locale detection with geo-IP support.
+ *
+ * Detection priority: path > cookie > geo (country) > Accept-Language header > default
+ *
+ * @example
+ * ```ts
+ * // In your middleware/loader:
+ * const languages = await i18n.getLanguages();
+ * const countryMap = buildCountryLocaleMap(languages);
+ *
+ * const result = detectLocale({
+ *   project: "acme/web",
+ *   defaultLocale: "en",
+ *   availableLocales: languages.map(l => l.code),
+ *   pathLocale: getLocaleFromURL(pathname),
+ *   cookieLocale: getCookie("locale"),
+ *   countryCode: request.cf?.country,     // Cloudflare
+ *   // countryCode: request.geo?.country,  // Vercel
+ *   countryLocaleMap: countryMap,
+ *   headerLocale: parseAcceptLanguage(request),
+ * });
+ *
+ * // result.locale = "tr"
+ * // result.detectedFrom = "geo"
+ * ```
  */
 export declare function detectLocale(options: LocaleDetectionOptions): LocaleDetectionResult;
 //# sourceMappingURL=detection.d.ts.map

package/dist/i18n/detection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detection.d.ts","sourceRoot":"","sources":["../../src/i18n/detection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAOhF;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAmCvB"}
+{"version":3,"file":"detection.d.ts","sourceRoot":"","sources":["../../src/i18n/detection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQlD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,cAAc,EAAE,GAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwDxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAyCvB"}

package/dist/i18n/detection.js

@@ -1,16 +1,111 @@
 import { normalizeLocale } from "../utils/locale.js";
+import { LANGUAGE_TO_COUNTRY } from "../utils/locale-ui.js";
 /** Case-insensitive locale lookup — returns the canonical (CDN) form if matched */
 const findLocale = (code, available) => code ? available.find((a) => normalizeLocale(a) === normalizeLocale(code)) : undefined;
 /**
- * Framework-agnostic locale detection logic
+ * Build a country→locale map from CDN manifest languages.
+ *
+ * Uses each language's `countryCode` field as the primary source
+ * (set in the Better i18n dashboard). Falls back to `LANGUAGE_TO_COUNTRY`
+ * reverse lookup for languages without explicit country codes.
+ *
+ * Also includes multi-country overrides (e.g. AT→de, MX→es) so that
+ * visitors from countries sharing a language are correctly mapped.
+ *
+ * @example
+ * ```ts
+ * const languages = await i18n.getLanguages();
+ * const countryMap = buildCountryLocaleMap(languages);
+ * // { tr: "tr", de: "de", jp: "ja", cn: "zh-hans", at: "de", mx: "es", ... }
+ * ```
+ */
+export function buildCountryLocaleMap(languages) {
+    const map = {};
+    const availableCodes = new Set(languages.map((l) => l.code));
+    // Primary: manifest countryCode → locale code
+    for (const lang of languages) {
+        if (lang.countryCode) {
+            map[lang.countryCode.toLowerCase()] = lang.code;
+        }
+    }
+    // Secondary: reverse LANGUAGE_TO_COUNTRY for languages with no countryCode
+    for (const lang of languages) {
+        if (!lang.countryCode) {
+            const country = LANGUAGE_TO_COUNTRY[lang.code]
+                || LANGUAGE_TO_COUNTRY[lang.code.split("-")[0]];
+            if (country && !map[country]) {
+                map[country] = lang.code;
+            }
+        }
+    }
+    // Multi-country overrides: countries whose primary language is available
+    // but they aren't the "home country" for that language
+    const MULTI_COUNTRY = {
+        // German-speaking
+        at: "de", ch: "de", li: "de",
+        // French-speaking
+        be: "fr", lu: "fr", mc: "fr",
+        // Spanish-speaking
+        mx: "es", ar: "es", co: "es", cl: "es", pe: "es",
+        ve: "es", ec: "es", gt: "es", cu: "es", do: "es",
+        hn: "es", sv: "es", ni: "es", cr: "es", pa: "es",
+        uy: "es", py: "es", bo: "es",
+        // Portuguese-speaking
+        br: "pt-br", ao: "pt", mz: "pt",
+        // Arabic-speaking
+        ae: "ar", eg: "ar", ma: "ar", dz: "ar", iq: "ar",
+        kw: "ar", qa: "ar", bh: "ar", om: "ar", jo: "ar", lb: "ar",
+        // Chinese-speaking
+        sg: "zh-hans", tw: "zh-hans", hk: "zh-hans", mo: "zh-hans",
+        // English-speaking (fallback)
+        us: "en", gb: "en", au: "en", nz: "en", ca: "en", ie: "en",
+        // Russian-speaking
+        by: "ru", kz: "ru", kg: "ru",
+        // Malay-speaking
+        bn: "ms",
+    };
+    for (const [country, locale] of Object.entries(MULTI_COUNTRY)) {
+        if (!map[country] && availableCodes.has(locale)) {
+            map[country] = locale;
+        }
+    }
+    return map;
+}
+/**
+ * Framework-agnostic locale detection with geo-IP support.
+ *
+ * Detection priority: path > cookie > geo (country) > Accept-Language header > default
+ *
+ * @example
+ * ```ts
+ * // In your middleware/loader:
+ * const languages = await i18n.getLanguages();
+ * const countryMap = buildCountryLocaleMap(languages);
+ *
+ * const result = detectLocale({
+ *   project: "acme/web",
+ *   defaultLocale: "en",
+ *   availableLocales: languages.map(l => l.code),
+ *   pathLocale: getLocaleFromURL(pathname),
+ *   cookieLocale: getCookie("locale"),
+ *   countryCode: request.cf?.country,     // Cloudflare
+ *   // countryCode: request.geo?.country,  // Vercel
+ *   countryLocaleMap: countryMap,
+ *   headerLocale: parseAcceptLanguage(request),
+ * });
+ *
+ * // result.locale = "tr"
+ * // result.detectedFrom = "geo"
+ * ```
  */
 export function detectLocale(options) {
-    const { pathLocale, cookieLocale, headerLocale, defaultLocale, availableLocales, } = options;
+    const { pathLocale, cookieLocale, headerLocale, countryCode, countryLocaleMap, defaultLocale, availableLocales, } = options;
     let locale;
     let detectedFrom;
-    // Priority: path > cookie > header > default
+    // Priority: path > cookie > geo > header > default
     const pathMatch = findLocale(pathLocale, availableLocales);
     const cookieMatch = findLocale(cookieLocale, availableLocales);
+    const geoMatch = resolveGeoLocale(countryCode, countryLocaleMap, availableLocales);
     const headerMatch = findLocale(headerLocale, availableLocales);
     if (pathMatch) {
         locale = pathMatch;
@@ -20,6 +115,10 @@ export function detectLocale(options) {
         locale = cookieMatch;
         detectedFrom = "cookie";
     }
+    else if (geoMatch) {
+        locale = geoMatch;
+        detectedFrom = "geo";
+    }
     else if (headerMatch) {
         locale = headerMatch;
         detectedFrom = "header";
@@ -32,4 +131,89 @@ export function detectLocale(options) {
     const shouldSetCookie = cookieLocale !== locale;
     return { locale, detectedFrom, shouldSetCookie };
 }
+/**
+ * Built-in multi-country overrides for countries that share a language
+ * with another country already in LANGUAGE_TO_COUNTRY.
+ * This allows geo detection to work without a manifest-driven map.
+ */
+const BUILT_IN_COUNTRY_OVERRIDES = {
+    // German-speaking
+    at: "de", ch: "de", li: "de",
+    // French-speaking
+    be: "fr", lu: "fr", mc: "fr",
+    // Spanish-speaking
+    mx: "es", ar: "es", co: "es", cl: "es", pe: "es",
+    ve: "es", ec: "es", gt: "es", cu: "es", hn: "es",
+    sv: "es", ni: "es", cr: "es", pa: "es", uy: "es",
+    py: "es", bo: "es", do: "es",
+    // Portuguese-speaking
+    br: "pt", ao: "pt", mz: "pt",
+    // Arabic-speaking
+    ae: "ar", eg: "ar", ma: "ar", dz: "ar", iq: "ar",
+    kw: "ar", qa: "ar", bh: "ar", om: "ar", jo: "ar", lb: "ar",
+    // Chinese-speaking
+    sg: "zh", tw: "zh", hk: "zh", mo: "zh",
+    // Russian-speaking
+    by: "ru", kz: "ru", kg: "ru",
+    // Malay-speaking
+    bn: "ms",
+    // English-speaking
+    us: "en", au: "en", nz: "en", ca: "en", ie: "en",
+};
+/**
+ * Fuzzy locale match — finds a locale in available list even when the
+ * base language matches but the full code differs.
+ * e.g., lang="zh", available=["zh-hans"] → returns "zh-hans"
+ * e.g., lang="pt", available=["pt-br", "pt"] → returns "pt"
+ */
+function fuzzyFindLocale(lang, available) {
+    // Exact match first
+    const exact = findLocale(lang, available);
+    if (exact)
+        return exact;
+    // Base language match (zh → zh-hans, pt → pt-br)
+    const base = lang.split("-")[0].toLowerCase();
+    return available.find((a) => a.toLowerCase().startsWith(base + "-"))
+        ?? available.find((a) => a.toLowerCase() === base);
+}
+/**
+ * Resolve a country code to a locale.
+ *
+ * Resolution chain:
+ * 1. Explicit countryLocaleMap (manifest-driven, most accurate)
+ * 2. LANGUAGE_TO_COUNTRY reverse lookup (built-in)
+ * 3. BUILT_IN_COUNTRY_OVERRIDES (multi-country fallback)
+ *
+ * All lookups use fuzzy matching so zh→zh-hans, pt→pt-br work.
+ */
+function resolveGeoLocale(countryCode, countryLocaleMap, availableLocales) {
+    if (!countryCode)
+        return undefined;
+    const normalized = countryCode.toLowerCase();
+    // 1. Explicit map (manifest-driven)
+    if (countryLocaleMap) {
+        const mapped = countryLocaleMap[normalized];
+        if (mapped) {
+            const match = fuzzyFindLocale(mapped, availableLocales);
+            if (match)
+                return match;
+        }
+    }
+    // 2. Reverse LANGUAGE_TO_COUNTRY (e.g., tr→"tr", ja→"jp")
+    for (const [lang, country] of Object.entries(LANGUAGE_TO_COUNTRY)) {
+        if (country === normalized) {
+            const match = fuzzyFindLocale(lang, availableLocales);
+            if (match)
+                return match;
+        }
+    }
+    // 3. Multi-country overrides (e.g., AT→de, MX→es, BR→pt)
+    const override = BUILT_IN_COUNTRY_OVERRIDES[normalized];
+    if (override) {
+        const match = fuzzyFindLocale(override, availableLocales);
+        if (match)
+            return match;
+    }
+    return undefined;
+}
 //# sourceMappingURL=detection.js.map

package/dist/i18n/detection.js.map

@@ -1 +1 @@
-{"version":3,"file":"detection.js","sourceRoot":"","sources":["../../src/i18n/detection.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,mFAAmF;AACnF,MAAM,UAAU,GAAG,CAAC,IAA+B,EAAE,SAAmB,EAAE,EAAE,CAC1E,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAEzF;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,OAA+B;IAE/B,MAAM,EACJ,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,GACjB,GAAG,OAAO,CAAC;IAEZ,IAAI,MAAc,CAAC;IACnB,IAAI,YAAmD,CAAC;IAExD,6CAA6C;IAC7C,MAAM,SAAS,GAAG,UAAU,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;IAC3D,MAAM,WAAW,GAAG,UAAU,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC;IAC/D,MAAM,WAAW,GAAG,UAAU,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC;IAE/D,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,GAAG,SAAS,CAAC;QACnB,YAAY,GAAG,MAAM,CAAC;IACxB,CAAC;SAAM,IAAI,WAAW,EAAE,CAAC;QACvB,MAAM,GAAG,WAAW,CAAC;QACrB,YAAY,GAAG,QAAQ,CAAC;IAC1B,CAAC;SAAM,IAAI,WAAW,EAAE,CAAC;QACvB,MAAM,GAAG,WAAW,CAAC;QACrB,YAAY,GAAG,QAAQ,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,aAAa,CAAC;QACvB,YAAY,GAAG,SAAS,CAAC;IAC3B,CAAC;IAED,0DAA0D;IAC1D,MAAM,eAAe,GAAG,YAAY,KAAK,MAAM,CAAC;IAEhD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,CAAC;AACnD,CAAC"}
+{"version":3,"file":"detection.js","sourceRoot":"","sources":["../../src/i18n/detection.ts"],"names":[],"mappings":"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"}

package/dist/i18n/types.d.ts

@@ -20,11 +20,30 @@ export interface LocaleDetectionOptions {
     pathLocale?: string | null;
     cookieLocale?: string | null;
     headerLocale?: string | null;
+    /**
+     * ISO 3166-1 alpha-2 country code from geo-IP detection.
+     * Pass this from your edge platform:
+     * - Cloudflare Workers: `request.cf?.country`
+     * - Vercel Edge: `request.geo?.country`
+     * - Node.js behind CF: `request.headers.get("CF-IPCountry")`
+     *
+     * Used with `countryLocaleMap` to resolve country → locale.
+     * Priority: path > cookie > geo (country) > header > default
+     */
+    countryCode?: string | null;
+    /**
+     * Country code → locale mapping. Built from CDN manifest's
+     * `languages[].countryCode` field via `buildCountryLocaleMap()`.
+     *
+     * If not provided but `countryCode` is set, falls back to
+     * `LANGUAGE_TO_COUNTRY` reverse lookup from core.
+     */
+    countryLocaleMap?: Record<string, string>;
     availableLocales: string[];
 }
 export interface LocaleDetectionResult {
     locale: string;
-    detectedFrom: "path" | "cookie" | "header" | "default";
+    detectedFrom: "path" | "cookie" | "geo" | "header" | "default";
     shouldSetCookie: boolean;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/i18n/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/i18n/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,SAAS,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvD,eAAe,EAAE,OAAO,CAAC;CAC1B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/i18n/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,SAAS,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC/D,eAAe,EAAE,OAAO,CAAC;CAC1B"}

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { createAutoStorage, createLocalStorage, createMemoryStorage } from "./st
 export { normalizeConfig, parseProject, getProjectBaseUrl } from "./config.js";
 export { extractLanguages } from "./manifest.js";
 export { createLogger } from "./logger.js";
-export { detectLocale } from "./i18n/detection.js";
+export { detectLocale, buildCountryLocaleMap } from "./i18n/detection.js";
 export { TtlCache, buildCacheKey } from "./cache.js";
 export { LANGUAGE_TO_COUNTRY, getCountryCodeFromLocale, getFlagEmoji, getLanguageLabel, resolveFlag, type ResolvedFlag, } from "./utils/locale-ui.js";
 export { normalizeLocale, extractLocale, getLocaleFromPath, hasLocalePrefix, removeLocalePrefix, addLocalePrefix, replaceLocaleInPath, createLocalePath, type LocaleConfig, } from "./utils/locale.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAGlF,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGhG,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAG/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGrD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,KAAK,YAAY,GAClB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAEV,cAAc,EACd,gBAAgB,EAChB,aAAa,EAGb,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EAGd,QAAQ,EACR,MAAM,EAGN,QAAQ,EAGR,kBAAkB,EAGlB,MAAM,EACN,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,GACb,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAGlF,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGhG,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAG/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG1E,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGrD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,KAAK,YAAY,GAClB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAEV,cAAc,EACd,gBAAgB,EAChB,aAAa,EAGb,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EAGd,QAAQ,EACR,MAAM,EAGN,QAAQ,EAGR,kBAAkB,EAGlB,MAAM,EACN,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,GACb,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -9,7 +9,7 @@ export { extractLanguages } from "./manifest.js";
 // Logger
 export { createLogger } from "./logger.js";
 // Middleware logic
-export { detectLocale } from "./i18n/detection.js";
+export { detectLocale, buildCountryLocaleMap } from "./i18n/detection.js";
 // Cache utilities
 export { TtlCache, buildCacheKey } from "./cache.js";
 // Locale UI utilities (flags, labels, country codes)

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,WAAW;AACX,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAElF,mBAAmB;AACnB,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEhG,0BAA0B;AAC1B,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE/E,qBAAqB;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,kBAAkB;AAClB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAErD,qDAAqD;AACrD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,WAAW,GAEZ,MAAM,sBAAsB,CAAC;AAE9B,mBAAmB;AACnB,OAAO,EACL,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,WAAW;AACX,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAElF,mBAAmB;AACnB,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEhG,0BAA0B;AAC1B,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE/E,qBAAqB;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE1E,kBAAkB;AAClB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAErD,qDAAqD;AACrD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,WAAW,GAEZ,MAAM,sBAAsB,CAAC;AAE9B,mBAAmB;AACnB,OAAO,EACL,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC"}

package/dist/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAEd,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAcpB;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,UAAU,gBAAgB,KACzB,cAAc,EAahB,CAAC"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAEd,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAepB;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,UAAU,gBAAgB,KACzB,cAAc,EAahB,CAAC"}

package/dist/manifest.js

@@ -6,6 +6,7 @@ const normalizeLanguage = (language) => ({
     name: language.name,
     nativeName: language.nativeName || language.name || language.code.toUpperCase(),
     flagUrl: language.flagUrl ?? null,
+    countryCode: language.countryCode ?? null,
     isDefault: language.isSource ?? false,
 });
 /**

package/dist/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,iBAAiB,GAAG,CAAC,QAA0B,EAAkB,EAAE,CAAC,CAAC;IACzE,IAAI,EAAE,QAAQ,CAAC,IAAI;IACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;IACnB,UAAU,EACR,QAAQ,CAAC,UAAU,IAAI,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE;IACrE,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,IAAI;IACjC,SAAS,EAAE,QAAQ,CAAC,QAAQ,IAAI,KAAK;CACtC,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,QAA0B,EACR,EAAE;IACpB,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;QACjD,CAAC,CAAC,QAAQ,CAAC,SAAS;QACpB,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO,SAAS;SACb,MAAM,CACL,CAAC,QAAQ,EAAgC,EAAE,CACzC,CAAC,CAAC,QAAQ;QACV,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ;QACjC,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAC3B;SACA,GAAG,CAAC,iBAAiB,CAAC,CAAC;AAC5B,CAAC,CAAC"}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,iBAAiB,GAAG,CAAC,QAA0B,EAAkB,EAAE,CAAC,CAAC;IACzE,IAAI,EAAE,QAAQ,CAAC,IAAI;IACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;IACnB,UAAU,EACR,QAAQ,CAAC,UAAU,IAAI,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE;IACrE,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,IAAI;IACjC,WAAW,EAAE,QAAQ,CAAC,WAAW,IAAI,IAAI;IACzC,SAAS,EAAE,QAAQ,CAAC,QAAQ,IAAI,KAAK;CACtC,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,QAA0B,EACR,EAAE;IACpB,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;QACjD,CAAC,CAAC,QAAQ,CAAC,SAAS;QACpB,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO,SAAS;SACb,MAAM,CACL,CAAC,QAAQ,EAAgC,EAAE,CACzC,CAAC,CAAC,QAAQ;QACV,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ;QACjC,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAC3B;SACA,GAAG,CAAC,iBAAiB,CAAC,CAAC;AAC5B,CAAC,CAAC"}

package/dist/types.d.ts

@@ -108,6 +108,8 @@ export interface ManifestLanguage {
     name?: string;
     nativeName?: string;
     flagUrl?: string | null;
+    /** ISO 3166-1 alpha-2 country code (e.g. "tr", "jp", "cn") */
+    countryCode?: string | null;
     isSource?: boolean;
     lastUpdated?: string | null;
     keyCount?: number;
@@ -138,6 +140,8 @@ export interface LanguageOption {
     name?: string;
     nativeName?: string;
     flagUrl?: string | null;
+    /** ISO 3166-1 alpha-2 country code (e.g. "tr", "jp", "cn") */
+    countryCode?: string | null;
     /**
      * Whether this is the default/source language
      */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/utils/locale.d.ts

@@ -20,10 +20,23 @@ export interface LocaleConfig {
      */
     locales: string[];
     /**
-     * Default locale code (will NOT have a prefix in URL)
+     * Default locale code
      * @example 'en'
      */
     defaultLocale: string;
+    /**
+     * URL prefix strategy for locale codes.
+     *
+     * - `"as-needed"` (default): Default locale has NO prefix (`/about`), others do (`/tr/about`).
+     *   Follows next-intl / Paraglide JS convention.
+     * - `"always"`: ALL locales get a prefix, including the default (`/en/about`, `/tr/about`).
+     *   Use with TanStack Router `$locale/` route segments.
+     * - `"never"`: NO locale prefix in URL for any locale. Locale is stored only in cookie.
+     *   Ideal for dashboards and apps where URL structure shouldn't change per locale.
+     *
+     * @default "as-needed"
+     */
+    localePrefix?: "always" | "as-needed" | "never";
 }
 /**
  * Extract locale from URL pathname
@@ -67,27 +80,43 @@ export declare function hasLocalePrefix(pathname: string, config: LocaleConfig):
  */
 export declare function removeLocalePrefix(pathname: string, config: LocaleConfig): string;
 /**
- * Add locale prefix to pathname (respects default locale convention)
+ * Add locale prefix to pathname
  *
- * Default locale does NOT get a prefix (follows next-intl/Paraglide JS pattern)
+ * Respects `localePrefix` config:
+ * - `"as-needed"` (default): default locale has no prefix
+ * - `"always"`: all locales get a prefix
+ * - `"never"`: no locale prefix for any locale (cookie-only)
  *
  * @example
+ * // as-needed (default)
  * addLocalePrefix('/about', 'tr', config) // '/tr/about'
- * addLocalePrefix('/about', 'en', config) // '/about' (en is default, no prefix)
- * addLocalePrefix('/', 'tr', config)      // '/tr'
+ * addLocalePrefix('/about', 'en', config) // '/about' (en is default)
+ *
+ * // always
+ * addLocalePrefix('/about', 'en', { ...config, localePrefix: 'always' }) // '/en/about'
+ *
+ * // never
+ * addLocalePrefix('/about', 'tr', { ...config, localePrefix: 'never' }) // '/about'
  */
 export declare function addLocalePrefix(pathname: string, locale: string, config: LocaleConfig): string;
 /**
  * Replace/add locale in pathname
  *
- * Handles the default locale specially (removes prefix instead of adding)
- * This is the main utility for locale switching in URLs
+ * Respects `localePrefix` config:
+ * - `"as-needed"` (default): default locale has no prefix
+ * - `"always"`: all locales always get a prefix
+ * - `"never"`: no locale prefix for any locale (cookie-only)
  *
  * @example
- * replaceLocaleInPath('/about', 'tr', config)    // '/tr/about'
+ * // as-needed (default)
  * replaceLocaleInPath('/tr/about', 'en', config) // '/about' (en is default)
  * replaceLocaleInPath('/tr/about', 'de', config) // '/de/about'
- * replaceLocaleInPath('/en/about', 'tr', config) // '/tr/about'
+ *
+ * // always
+ * replaceLocaleInPath('/tr/about', 'en', { ...config, localePrefix: 'always' }) // '/en/about'
+ *
+ * // never
+ * replaceLocaleInPath('/tr/about', 'de', { ...config, localePrefix: 'never' }) // '/about'
  */
 export declare function replaceLocaleInPath(pathname: string, newLocale: string, config: LocaleConfig): string;
 /**

package/dist/utils/locale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/utils/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,MACR,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,MAAM,GAAG,IAAI,CASf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,OAAO,CAET;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,MAAM,CAMR;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GACnB,MAAM,CAUR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,GACnB,MAAM,CAWR;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,IAC3C,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,MAAM,CAI/C"}
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/utils/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,MACR,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,MAAM,GAAG,IAAI,CASf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,OAAO,CAET;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,MAAM,CAMR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GACnB,MAAM,CAeR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,GACnB,MAAM,CAgBR;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,IAC3C,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,MAAM,CAI/C"}

package/dist/utils/locale.js

@@ -69,18 +69,31 @@ export function removeLocalePrefix(pathname, config) {
     return result || "/";
 }
 /**
- * Add locale prefix to pathname (respects default locale convention)
+ * Add locale prefix to pathname
  *
- * Default locale does NOT get a prefix (follows next-intl/Paraglide JS pattern)
+ * Respects `localePrefix` config:
+ * - `"as-needed"` (default): default locale has no prefix
+ * - `"always"`: all locales get a prefix
+ * - `"never"`: no locale prefix for any locale (cookie-only)
  *
  * @example
+ * // as-needed (default)
  * addLocalePrefix('/about', 'tr', config) // '/tr/about'
- * addLocalePrefix('/about', 'en', config) // '/about' (en is default, no prefix)
- * addLocalePrefix('/', 'tr', config)      // '/tr'
+ * addLocalePrefix('/about', 'en', config) // '/about' (en is default)
+ *
+ * // always
+ * addLocalePrefix('/about', 'en', { ...config, localePrefix: 'always' }) // '/en/about'
+ *
+ * // never
+ * addLocalePrefix('/about', 'tr', { ...config, localePrefix: 'never' }) // '/about'
  */
 export function addLocalePrefix(pathname, locale, config) {
-    // Don't add prefix for default locale
-    if (locale === config.defaultLocale) {
+    // Never add prefix — locale is cookie-only
+    if (config.localePrefix === "never") {
+        return pathname;
+    }
+    // Don't add prefix for default locale in "as-needed" mode
+    if (config.localePrefix !== "always" && locale === config.defaultLocale) {
         return pathname;
     }
     if (pathname === "/" || pathname === "") {
@@ -91,20 +104,31 @@ export function addLocalePrefix(pathname, locale, config) {
 /**
  * Replace/add locale in pathname
  *
- * Handles the default locale specially (removes prefix instead of adding)
- * This is the main utility for locale switching in URLs
+ * Respects `localePrefix` config:
+ * - `"as-needed"` (default): default locale has no prefix
+ * - `"always"`: all locales always get a prefix
+ * - `"never"`: no locale prefix for any locale (cookie-only)
  *
  * @example
- * replaceLocaleInPath('/about', 'tr', config)    // '/tr/about'
+ * // as-needed (default)
  * replaceLocaleInPath('/tr/about', 'en', config) // '/about' (en is default)
  * replaceLocaleInPath('/tr/about', 'de', config) // '/de/about'
- * replaceLocaleInPath('/en/about', 'tr', config) // '/tr/about'
+ *
+ * // always
+ * replaceLocaleInPath('/tr/about', 'en', { ...config, localePrefix: 'always' }) // '/en/about'
+ *
+ * // never
+ * replaceLocaleInPath('/tr/about', 'de', { ...config, localePrefix: 'never' }) // '/about'
  */
 export function replaceLocaleInPath(pathname, newLocale, config) {
     // Remove existing locale prefix if present
     const cleanPath = removeLocalePrefix(pathname, config);
-    // Don't add prefix for default locale
-    if (newLocale === config.defaultLocale) {
+    // Never add prefix — locale is cookie-only
+    if (config.localePrefix === "never") {
+        return cleanPath;
+    }
+    // In "as-needed" mode, don't add prefix for default locale
+    if (config.localePrefix !== "always" && newLocale === config.defaultLocale) {
         return cleanPath;
     }
     // Add new locale prefix

package/dist/utils/locale.js.map

@@ -1 +1 @@
-{"version":3,"file":"locale.js","sourceRoot":"","sources":["../../src/utils/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAc,EAAU,EAAE,CACxD,MAAM,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAmB1C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,MAAoB;IAEpB,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEjC,IAAI,YAAY,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAC1D,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,OAAO,IAAI,CAAC,CAAC,oCAAoC;AACnD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAgB,EAChB,MAAoB;IAEpB,OAAO,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,aAAa,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,MAAoB;IAEpB,OAAO,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;AAClD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,MAAoB;IAEpB,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAC;IAE7B,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/D,OAAO,MAAM,IAAI,GAAG,CAAC;AACvB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,MAAc,EACd,MAAoB;IAEpB,sCAAsC;IACtC,IAAI,MAAM,KAAK,MAAM,CAAC,aAAa,EAAE,CAAC;QACpC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QACxC,OAAO,IAAI,MAAM,EAAE,CAAC;IACtB,CAAC;IACD,OAAO,IAAI,MAAM,GAAG,QAAQ,EAAE,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,SAAiB,EACjB,MAAoB;IAEpB,2CAA2C;IAC3C,MAAM,SAAS,GAAG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAEvD,sCAAsC;IACtC,IAAI,SAAS,KAAK,MAAM,CAAC,aAAa,EAAE,CAAC;QACvC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,wBAAwB;IACxB,OAAO,IAAI,SAAS,GAAG,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAoB;IACnD,OAAO,CAAC,IAAY,EAAE,MAAe,EAAU,EAAE;QAC/C,MAAM,YAAY,GAAG,MAAM,IAAI,MAAM,CAAC,aAAa,CAAC;QACpD,OAAO,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"locale.js","sourceRoot":"","sources":["../../src/utils/locale.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Framework-agnostic core utilities for Better i18n",
   "license": "MIT",
   "repository": {