imba-localization 0.4.12 → 0.5.0

package/README.md

@@ -8,6 +8,7 @@ A lightweight Imba module for loading and handling JSON-based localization files
 - 🔍 **Automatic language detection** - Uses the user's browser language settings
 - 💾 **Persistence**: Stores user choice in local storage across sessions
 - 🔄 **Smart fallback system** - Falls back to a default language when needed
+- 📦 **Optional split loading** - Loads only the selected language file and caches languages on demand
 - 🧠 **Intuitive access** - Proxy-based access to translation strings
 - 📡 **Event handling** - Support for `onready`, `onchange`, and `onerror` events
 - 🧾 **Type declarations** - Includes package-level TypeScript declarations for editor and language-server imports
@@ -30,6 +31,13 @@ npm install imba-localization
 bun add imba-localization
 ```
 
+For local module development:
+
+```bash
+bun install
+bun run test
+```
+
 ## 🚀 Quick Start
 
 ### 1️⃣ Preload the localization file
@@ -71,9 +79,9 @@ loc.onready = do
 
 loc.onerror = do(error, details)
   # The Localization object can return following types of errors:
-  # 'no_localization_file' - if there were a problem when downloading JSON file
-  # 'no_default_localization' - if there is no localization in the file for the default language
-  # 'no_localization_key' - if there is no requiered (from the interface) key in the file
+  # 'localization-no-file' - if there was a problem downloading a JSON file
+  # 'localization-no-default' - if there is no default localization
+  # 'localization-no-key' - if a requested interface key is missing
   console.error "Localization error:", error, details
 
 loc.onchange = do(lang_key)
@@ -94,7 +102,9 @@ console.log loc.languages[loc.active]
 
 ```
 
-## 📄 JSON Structure
+## 📄 Bundle JSON Structure
+
+The original single-file format remains supported and is the default mode:
 
 Your localization file should follow this format:
 
@@ -119,22 +129,80 @@ Your localization file should follow this format:
 }
 ```
 
+## 📦 Split Language Files
+
+Split mode loads a small manifest first and then downloads only the selected language. Previously loaded languages are kept in memory and are not requested again.
+
+```imba
+const loc = new Localization('/localization/languages.json', 'en', {split: true})
+
+# Optional when application startup needs to wait explicitly.
+await loc.pending
+
+# Assignment still works and starts an asynchronous language switch.
+loc.active = 'fr'
+
+# Use `use` when the caller needs to wait for the new dictionary.
+await loc.use('fr')
+```
+
+Recommended file structure:
+
+```text
+public/localization/
+├── languages.json
+├── en.json
+├── fr.json
+└── ru.json
+```
+
+`languages.json` contains only language metadata and file locations:
+
+```json
+{
+  "default": "en",
+  "languages": {
+    "en": { "name": "English", "flag": "us", "src": "en.json" },
+    "fr": { "name": "Français", "flag": "fr", "src": "fr.json" },
+    "ru": { "name": "Русский", "flag": "ru", "src": "ru.json" }
+  }
+}
+```
+
+Each language file contains the dictionary directly:
+
+```json
+{
+  "welcome": "Welcome",
+  "goodbye": "Goodbye",
+  "user": {
+    "profile": "Profile",
+    "settings": "Settings"
+  }
+}
+```
+
+If `src` is omitted, the language code is used as the filename (`ru` → `ru.json`). The manifest `default` overrides the constructor fallback when present. A failed switch keeps the current language active and reports `localization-no-file` through `onerror`.
+
 ## 🛠️ API Reference
 
 ### Constructor
 
 ```imba
-new Localization(url, default = 'en')
+new Localization(url, default = 'en', options = {})
 ```
 
 - `url`: Path to your JSON localization file
 - `default`: Fallback language code (defaults to 'en')
+- `options.split`: Treat `url` as a language manifest and load dictionaries on demand
 
 ### Properties
 
 - `active`: Get or set the code of the active language
-- `languages`: Object containing all loaded language data
+- `languages`: Available languages; unloaded split entries contain only `$` metadata
 - `preferred`: Detected browser language (first 2 characters of `navigator.language`)
+- `loaded`: Map of language codes whose dictionaries are already in memory
+- `pending`: Promise settled after initial localization loading finishes
 
 ### Methods
 
@@ -142,6 +210,8 @@ new Localization(url, default = 'en')
 - `text(path, fallback = '', data = null)`: Reads a localized string and replaces `{key}` placeholders from `data`
 - `table(path)`: Reads a nested object table, returning `{}` when missing
 - `render(value, data = null)`: Replaces `{key}` placeholders in any string-like value
+- `use(language)`: Loads and activates a language, returning a Promise
+- `load(language)`: Loads a split dictionary without activating it
 
 ### Events
 

package/index.d.ts

@@ -1,13 +1,26 @@
 export type LocalizationLanguage = Record<string, any>;
 export type LocalizationLanguages = Record<string, LocalizationLanguage>;
 
+export interface LocalizationOptions {
+  split?: boolean;
+}
+
+export interface LocalizationManifestLanguage {
+  name?: string;
+  flag?: string;
+  src?: string;
+  [key: string]: unknown;
+}
+
+export type LocalizationManifest = Record<string, string | LocalizationManifestLanguage>;
+
 export interface LocalizationErrorState {
   cache: Record<string, boolean>;
   throw(code: string, details?: any): void;
 }
 
 export class Localization {
-  constructor(url: string, fallback?: string);
+  constructor(url: string, fallback?: string, options?: LocalizationOptions);
 
   onready?: () => void;
   onerror?: (error: string, details?: any) => void;
@@ -17,6 +30,11 @@ export class Localization {
   preferred: string;
   default: string;
   ready: boolean;
+  mode: "bundle" | "split";
+  source: string;
+  manifest: LocalizationManifest;
+  loaded: Record<string, boolean>;
+  pending: Promise<void>;
   err: LocalizationErrorState;
 
   active: string;
@@ -25,6 +43,8 @@ export class Localization {
   lookup(path: string | string[], fallback?: unknown): unknown;
   text(path: string | string[], fallback?: string, data?: Record<string, unknown> | null): string;
   table(path: string | string[]): Record<string, any>;
+  use(language: string): Promise<string>;
+  load(language: string): Promise<boolean>;
 
   [key: string]: any;
 }

package/localization.imba

@@ -1,4 +1,6 @@
 # Emoji flags mapping - comprehensive list by region
+export {Localization} from './state.imba'
+
 export const flags = {
 	# Europe
 	'gb': '🇬🇧', 'us': '🇺🇸', 'ru': '🇷🇺', 'de': '🇩🇪', 'fr': '🇫🇷',
@@ -62,97 +64,6 @@ export const flags = {
 	'dg': '🇩🇬', 'ea': '🇪🇦', 'ic': '🇮🇨', 'xk': '🇽🇰'
 }
 
-export class Localization
-	onready
-	onerror
-	onchange
-	languages = {}
-	preferred = (window..navigator..language || 'en-US').slice(0, 2)
-	default
-	ready = false
-	err = {
-		cache: {}
-		throw: do(code, details)
-			return if err.cache[code]
-			if onerror isa Function and ready
-				onerror(code, details)
-			else
-				console.log "Localization error:", code, details
-			err.cache[code] = true
-	}
-
-	def constructor url, fallback = 'en'
-		default = fallback
-		window.fetch(url)
-		.then(do(response) response.json!)
-		.then(do(data) _finalize(data, undefined))
-		.catch(do(error) _finalize(undefined, error))
-		
-		return new Proxy self, {
-			get: do(target, p, receiver)
-				if Reflect.has(target, p)
-					return Reflect.get(target, p, receiver)
-				if !target.ready
-					target.err.throw("Request before localization is ready:", p)
-					return
-				return if target.err.cache[p]
-				return target.languages[p] if target.languages[p]
-				return target.languages[target.active][p] if target.languages[target.active] and target.languages[target.active][p]
-				target.err.throw('localization-no-key', p)
-				return ''
-		}
-
-	def render value, data = null
-		let text = String(value or '')
-		return text unless data and typeof data == 'object'
-		text.replace /\{([^}]+)\}/g, do(_match, key)
-			const value = data[key]
-			if value == undefined or value == null then '' else String(value)
-
-	def lookup path, fallback = ''
-		const keys = if Array.isArray(path) then path else String(path or '').split('.').filter(do(part) part)
-		let value = languages..[active] or languages..[default] or {}
-		for key in keys
-			if value and typeof value == 'object' and value[key] != undefined
-				value = value[key]
-			else
-				return fallback
-		value
-
-	def text path, fallback = '', data = null
-		const value = lookup(path, fallback)
-		return render(value, data) if typeof value == 'string' or typeof value == 'number'
-		render(fallback, data)
-
-	def table path
-		const value = lookup(path, {})
-		if value and typeof value == 'object' then value else {}
-				
-	def _finalize data, error
-		if error or !data
-			err.throw('localization-no-file',error) 
-		elif !data[default]
-			err.throw('localization-no-default', default)
-		else
-			languages = data
-			ready = true
-			err.cache = {}
-			onready! if onready isa Function
-			onchange(active) if onchange isa Function
-
-	get active
-		const saved = window.localStorage.getItem('imba-localization')
-		return saved if saved and languages[saved]
-		return preferred if languages[preferred]
-		return default 
-	
-	set active name
-		name = name and languages[name] ? name : active
-		if window.localStorage.getItem('imba-localization') != name
-			window.localStorage.setItem('imba-localization', name)
-			onchange(name) if onchange isa Function
-			err.cache = {}
-
 export const path-arrow-down = <path d="M213.66,165.66a8,8,0,0,1-11.32,0L128,91.31,53.66,165.66a8,8,0,0,1-11.32-11.32l80-80a8,8,0,0,1,11.32,0l80,80A8,8,0,0,1,213.66,165.66Z">
 
 tag language-selector

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imba-localization",
-  "version": "0.4.12",
+  "version": "0.5.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/HeapVoid/imba-localization.git"
@@ -25,8 +25,17 @@
   "keywords": ["imba", "theme", "localization"],
   "license": "MIT",
   "type": "module",
+  "scripts": {
+    "test": "bimba state.imba --outdir .cache/test --external imba --external imba/runtime && bun test"
+  },
+  "devDependencies": {
+    "bimba-cli": "latest",
+    "imba": "latest",
+    "typescript": "^5.9.3"
+  },
   "files": [
     "localization.imba",
+    "state.imba",
     "index.d.ts"
   ]
 }

package/state.imba

@@ -0,0 +1,195 @@
+export class Localization
+	onready
+	onerror
+	onchange
+	languages = {}
+	preferred = (window..navigator..language || 'en-US').slice(0, 2)
+	default
+	ready = false
+	mode = 'bundle'
+	source = ''
+	manifest = {}
+	loaded = {}
+	loading = {}
+	pending
+	#active = null
+	#request = 0
+	err = {
+		cache: {}
+		throw: do(code, details)
+			return if err.cache[code]
+			if onerror isa Function
+				onerror(code, details)
+			else
+				console.log "Localization error:", code, details
+			err.cache[code] = true
+	}
+
+	def constructor url, fallback = 'en', options = {}
+		default = fallback
+		source = url
+		mode = options..split ? 'split' : 'bundle'
+		pending = if mode == 'split' then _manifest! else _bundle!
+
+		return new Proxy self, {
+			get: do(target, p, receiver)
+				if Reflect.has(target, p)
+					return Reflect.get(target, p, receiver)
+				if !target.ready
+					target.err.throw("Request before localization is ready:", p)
+					return
+				return if target.err.cache[p]
+				return target.languages[p] if target.languages[p]
+				return target.languages[target.active][p] if target.languages[target.active] and target.languages[target.active][p]
+				target.err.throw('localization-no-key', p)
+				return ''
+		}
+
+	def render value, data = null
+		let text = String(value or '')
+		return text unless data and typeof data == 'object'
+		text.replace /\{([^}]+)\}/g, do(_match, key)
+			const value = data[key]
+			if value == undefined or value == null then '' else String(value)
+
+	def lookup path, fallback = ''
+		const keys = if Array.isArray(path) then path else String(path or '').split('.').filter(do(part) part)
+		let value = languages..[active] or languages..[default] or {}
+		for key in keys
+			if value and typeof value == 'object' and value[key] != undefined
+				value = value[key]
+			else
+				return fallback
+		value
+
+	def text path, fallback = '', data = null
+		const value = lookup(path, fallback)
+		return render(value, data) if typeof value == 'string' or typeof value == 'number'
+		render(fallback, data)
+
+	def table path
+		const value = lookup(path, {})
+		if value and typeof value == 'object' then value else {}
+
+	def use name
+		name = name and languages[name] ? name : active
+		return active unless name
+		const request = ++#request
+		if mode == 'split' and !loaded[name]
+			unless await load(name)
+				imba.commit!
+				return active
+		return active if request != #request
+		_activate(name)
+
+	def load name
+		return false unless languages[name]
+		return true if loaded[name]
+		return await loading[name] if loading[name]
+		loading[name] = _load(name)
+		const success = await loading[name]
+		delete loading[name]
+		success
+
+	def _load name
+		try
+			const data = await _read(_resolve(name))
+			const content = if data..[name] and data[name]..$ then data[name] else data
+			unless content and typeof content == 'object' and !Array.isArray(content)
+				throw new Error("Localization file for {name} is not an object")
+			const settings = _settings(name)
+			const language = Object.assign({}, content)
+			language.$ = Object.assign({}, content..$, settings)
+			languages[name] = language
+			loaded[name] = true
+			return true
+		catch error
+			err.throw('localization-no-file', {language: name, url: _resolve(name), error})
+			return false
+
+	def _bundle
+		try
+			_finalize(await _read(source), undefined)
+		catch error
+			_finalize(undefined, error)
+
+	def _manifest
+		try
+			const data = await _read(source)
+			const catalog = data..languages
+			default = data.default if data..default isa 'string'
+			unless catalog and typeof catalog == 'object' and !Array.isArray(catalog) and Object.keys(catalog).length
+				throw new Error('Localization manifest has no languages')
+			manifest = catalog
+			for own name of manifest
+				languages[name] = {$: _settings(name)}
+			unless languages[default]
+				err.throw('localization-no-default', default)
+				return
+			let name = _select!
+			let success = await load(name)
+			if !success and name != default
+				name = default
+				success = await load(name)
+			return unless success
+			_finish(name)
+		catch error
+			err.throw('localization-no-file', {url: source, error})
+
+	def _read url
+		const response = await window.fetch(url)
+		unless response.ok
+			throw new Error("Localization request failed with status {response.status}")
+		await response.json!
+
+	def _resolve name
+		const settings = _settings(name)
+		const file = settings.src or "{name}.json"
+		new window.URL(file, new window.URL(source, window.location.href)).toString!
+
+	def _settings name
+		const settings = manifest[name]
+		return {src: settings} if settings isa 'string'
+		settings or {}
+
+	def _select
+		const saved = window.localStorage.getItem('imba-localization')
+		return saved if saved and languages[saved]
+		return preferred if languages[preferred]
+		default
+
+	def _activate name
+		return active unless languages[name] and loaded[name]
+		const changed = #active != name
+		#active = name
+		if window.localStorage.getItem('imba-localization') != name
+			window.localStorage.setItem('imba-localization', name)
+		err.cache = {}
+		onchange(name) if changed and onchange isa Function
+		imba.commit! if ready
+		#active
+
+	def _finish name
+		#active = name
+		ready = true
+		err.cache = {}
+		onready! if onready isa Function
+		onchange(name) if onchange isa Function
+		imba.commit!
+
+	def _finalize data, error
+		if error or !data
+			err.throw('localization-no-file', error)
+		elif !data[default]
+			err.throw('localization-no-default', default)
+		else
+			languages = data
+			loaded = {}
+			loaded[name] = true for own name of languages
+			_finish(_select!)
+
+	get active
+		#active or _select!
+
+	set active name
+		use(name)