Development documentation · Some APIs may be unreleased Published release →

Guides

Localization: strings for your application

Development (2026-10-28): this API now has its own Neo.Localization.dll assembly. Update former System imports and rebuild consumers with the matching libraries.

Neo.Localization separates resource lookup from cultural formatting. Load a JSON catalogue from a directory you choose, then use Localizer for key-based lookup. Localizer<T> associates resources with a feature 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

Small JSON catalogues

Resources are flat UTF-8 JSON objects whose keys and values are strings:

{"Greeting":"Hej {0}!","menu.save":"Spara","empty":""}

Dots are literal key characters. Keys are case-sensitive and ordinal; translated text retains its Unicode content. Empty translations count as present.

Choose a directory and optional scope

JsonLocalizerProvider(directory) configures loading without performing I/O. Load(culture) selects unscoped resources. Load(culture, scope) selects a feature, and Load<T>(culture) uses the type's simple name as its scope. Loading returns a Result, making file or catalogue errors explicit.

For Swedish resources, each key is resolved in this order:

Scope Regional Language Invariant
None sv-SE.json sv.json invariant.json
FeatureX FeatureX.sv-SE.json FeatureX.sv.json FeatureX.json

Fallback is per key, so a regional file need contain only its overrides. Missing files are skipped. Set fallbackToInvariant: false on the provider to omit the invariant fallback; explicitly selecting Culture.Invariant still loads it.

Lookup first, then format

strings["Greeting", name] resolves the translation before inserting arguments using composite placeholders such as {0}. A missing resource returns the key unchanged. strings.Find("Greeting", name) instead returns None when absent. Without arguments, lookup returns the stored template unchanged. These assertions come from the built-in localization contract tests:

_ = Assert.Equal("Hej Raven!", strings["Greeting", "Raven"])?
_ = Assert.Equal("Hej {0}!", strings["Greeting"])?

Formatting uses the selected culture even when the translation comes from a fallback file. Invalid composite templates follow String.Format error behavior; Find distinguishes missing resources, not malformed formatting.

Attach WithMissingKeyHandler to report absent display keys to a console or logger. Find remains quiet, and successful fallback does not trigger a missing-key report.

Use a localizer through dependency injection

Register a configured factory once. An open generic registration supplies Localizer<T> for each resource type requested by a consumer:

let resources = JsonLocalizerProvider("resources")
let services: ServiceCollection = DefaultServiceCollection()
_ = Assert.True(services.AddLocalization(JsonLocalizerFactory(resources, Culture.SwedishSweden)) is Ok(_), "Register resources")?
_ = Assert.True(services.AddScoped<LocalizedGreeting>() is Ok(_), "Register consumer")?
let Ok(provider) = services.Build() else {
    return Assert.True(false, "Build localized graph")
}
use root = provider
let Ok(createdScope) = root.CreateScope() else {
    return Assert.True(false, "Create scope")
}
use scope = createdScope
let Ok(first) = scope.GetRequiredService<LocalizedGreeting>() else {
    return Assert.True(false, "Resolve localized service")
}

This excerpt comes from the built-in localization contract test; its assertions propagate TestFailure when setup fails. The scoped consumer formats "Totalt {0:F2}" from FeatureX.json as "Totalt 12,00" for Swedish, while a regional key still comes from FeatureX.sv-SE.json. Native applications must retain the consumer's constructor and DefaultLocalizer constructors for activation, as described in the dependency injection sample.

A bounded foundation

Reuse loaded localizers. Loading creates owned catalogues; ordinary lookup reuses stored strings without allocating a result wrapper. Formatting creates result text; fixed overloads for one to three arguments avoid an argument array.

This foundation supports the five built-in cultures and flat string catalogues, with a 64 KiB and 4,096-entry limit per file. Nested resources, plural rules, reload watching and shared concurrent caching are not implemented. The JSON DI factory reuses a lazy catalogue per resource type; direct provider.Load calls load independently. File loading is synchronous; borrowed input streams can be read asynchronously. Current native/JIT file loading requires the macOS host file-input service.

Localization API reference → · Culture and formatting →

In development builds, keep retention in App.retention.json beside App.rvnproj. Add this entry to its types array alongside the consumer's constructor entry:

{
  "name": "Neo.Localization.DefaultLocalizer`1",
  "retain": ["constructors"]
}

The complete file has "schemaVersion": 1 and a "types" array. The native project builder reads it automatically; --retention-file selects another file. Retention modes and boundaries →

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.

The provider-neutral contracts, typed adapter, formatting and diagnostic decorators now live in Neo.Localization.Abstractions, which references only System.Runtime. JSON resources and DI integration remain in Neo.Localization, using DI abstractions.