Development documentation · Some APIs may be unreleased Published release →

Guides

Localization (development)

Neo.Localization.Localizer provides strings[key] and Find(key). The indexer returns the key when absent; Find returns Optional<string>. Empty translations are present. Keys are ordinal and case-sensitive; stored UTF-8 text is preserved. Localizer<T> associates a catalogue with a resource type.

Try it

Create a small JSON catalogue and format a translated string. A missing key returns the key itself.

module Examples.Extensions.Introductions.Localization

import System.*
import System.Result.*
import Neo.Localization.*

func Main() -> int {
    let Ok(strings) = JsonLocalizerProvider.Create("{\"Greeting\":\"Hej {0}!\"}") else { return 1 }
    Console.WriteLine(strings["Greeting", "Ada"])
    return 0
}

Complete sample project · Build and run instructions

JSON provider

Neo.Localization.Abstractions.dll owns the lookup/factory contracts, typed adapter, formatting and missing-key diagnostics and references only System.Runtime. Neo.Localization.dll owns JSON providers, loading errors and DI registration, referencing System.Runtime, System.Data, Neo.Localization.Abstractions and Neo.DependencyInjection.Abstractions. Namespaces remain Neo.Localization. The native reference includes their members. Replace old System.Localization imports and retention names and rebuild consumers; there is no old-name compatibility shim. See the assembly boundary and migration.

Construct JsonLocalizerProvider(directory) to enable invariant fallback, or JsonLocalizerProvider(directory, fallbackToInvariant: false) to disable it. Construction performs no I/O. Load(culture) loads unscoped resources; Load(culture, scope) selects an explicit scope. Load<T>(culture) returns Result<Localizer<T>, LocalizationError> and uses T's nominal simple name as scope. Structural types are rejected. Types with identical simple names share a scope; use an explicit scope for collision avoidance or stability across renames.

Selection Files in priority order
Swedish, scope FeatureX FeatureX.sv-SE.json, FeatureX.sv.json, FeatureX.json
Swedish, no scope sv-SE.json, sv.json, invariant.json
Invariant, scope FeatureX FeatureX.json
Invariant, no scope invariant.json

Fallback is per key. Empty values override fallbacks. Disabling automatic invariant fallback omits the last file for a non-invariant culture; explicitly selecting Culture.Invariant always reads it. Culture selection uses the existing five formatting profiles; arbitrary locale tags/script fallback are future work. Missing files are skipped, and all-missing returns an empty catalogue. Other I/O, UTF-8, syntax, duplicate-key and limit failures return errors, including failures in fallback files. Only the configured directory is used. Scope cannot contain NUL, slash, backslash or colon, or be ./...

Each file is a flat JSON object of strings:

{"hello":"Hej världen","empty":"","menu.save":"Spara"}

Dots are literal key characters. This is the simple JSON format supported by localization tools, not full i18next or ICU MessageFormat. Nested objects, arrays, numbers, booleans and null values are rejected. Plural selection, named interpolation, ambient culture, reload watching and resource discovery are not implemented. Each file is limited to 65536 UTF-8 bytes and 4096 entries; JSON escapes and surrogate pairs are validated. Duplicate names are checked after escape decoding.

Create(string) and Create(ReadOnlySlice<byte>) parse an in-memory catalogue. The byte input is borrowed only for the call; the returned catalogue owns its strings. Static Load(path) reads one explicit file synchronously through the current blocking storage provider. Instance Load methods also perform blocking file reads. Read(InputStream) returns a Task, reads through EOF and leaves the borrowed stream open. It uses bounded text buffering; it is not an incremental JSON parser. File resources are closed by the storage provider before return.

Formatted lookup

Localizer.Culture is the selected formatting culture. Single-file and in-memory catalogues use invariant culture. Culture-based loading retains the requested culture regardless of which fallback supplies a template.

LocalizerFormatting adds indexers and Find overloads for one, two or three object? arguments and a params object?[] argument list. Lookup happens first: strings["Greeting", name] formats a resolved template, or returns the key unchanged. strings.Find("Greeting", name) returns Some(formatted) or None. No-argument lookup preserves the raw template. Null arguments produce empty text. Templates use String.Format composite syntax, alignment and format specifiers; malformed formats retain its terminal failure contract, rather than becoming missing keys. Fixed overloads avoid an argument array; value arguments may box and formatting can allocate output text. Import Neo.Localization.* to use the extensions.

Missing-key diagnostics

strings.WithMissingKeyHandler(handler) returns a wrapper. It calls the handler once per missing indexer lookup, then returns the key. Find remains quiet and empty translations do not trigger the callback. Attach diagnostics after loading the fallback chain so only genuinely absent keys are reported. The application can capture culture/scope and call Console.WriteLine, a logger or a counter. Handlers run synchronously; throttling and avoiding recursive lookup are caller responsibilities. Handler failures propagate. The original localizer is unchanged.

Loading allocates the owned catalogue; lookups reuse stored strings and do not allocate a LocalizedString wrapper. HashMap is used with ordinal equality. Concurrent access is not currently promised by the underlying map implementation. Keep loaded instances for reuse; the provider does not cache them automatically. Native/JIT file loading currently uses the macOS host file-input service; Windows native file input remains a host capability gap. Interpreter storage uses its existing host implementation.

Localization feature guide

Dependency injection (development)

LocalizerFactory.Create(resourceType: TypeInfo) -> Localizer is the nongeneric factory contract. DefaultLocalizer<T>(factory: LocalizerFactory) implements Localizer<T> by delegating to factory.Create(typeof(T)).

JsonLocalizerFactory(provider: JsonLocalizerProvider, culture: Culture) fixes resource configuration and culture without I/O. Create caches a lazy localizer per exact resource type. First lookup synchronously loads the fallback chain; invalid resources fault. Use provider.Load(culture, resourceType) for a recoverable Result<Localizer, LocalizationError> instead. Find reports a missing key, not loading or formatting errors. Instances are for serialized guest access.

ServiceCollection.AddLocalization(factory: LocalizerFactory) returns Result<unit, ServiceError>. It conditionally registers the caller-owned singleton factory and open transient Localizer<> -> DefaultLocalizer<> mapping. Existing explicit registrations win. Different resource types need no separate registration. Each resolution creates a small typed adapter; the JSON factory reuses catalogues. Retain DefaultLocalizer's constructors for native activation, as well as consumer constructors. No ambient culture, reload or plural rules are introduced.

For a native project, add the adapter retention alongside your consumer roots:

--reflection-constructor-type 'Neo.Localization.DefaultLocalizer`1'

The native project builder resolves this exact metadata name from the supplied class-library modules. It retains the closed adapter shapes observed through Localizer<T> requests; it does not enable arbitrary runtime code generation.