MASA.Lingua.SDK.AspNetCore 0.0.1-preview.3

Prefix Reserved
This is a prerelease version of MASA.Lingua.SDK.AspNetCore.
dotnet add package MASA.Lingua.SDK.AspNetCore --version 0.0.1-preview.3
                    
NuGet\Install-Package MASA.Lingua.SDK.AspNetCore -Version 0.0.1-preview.3
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="MASA.Lingua.SDK.AspNetCore" Version="0.0.1-preview.3" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="MASA.Lingua.SDK.AspNetCore" Version="0.0.1-preview.3" />
                    
Directory.Packages.props
<PackageReference Include="MASA.Lingua.SDK.AspNetCore" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add MASA.Lingua.SDK.AspNetCore --version 0.0.1-preview.3
                    
#r "nuget: MASA.Lingua.SDK.AspNetCore, 0.0.1-preview.3"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package MASA.Lingua.SDK.AspNetCore@0.0.1-preview.3
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=MASA.Lingua.SDK.AspNetCore&version=0.0.1-preview.3&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=MASA.Lingua.SDK.AspNetCore&version=0.0.1-preview.3&prerelease
                    
Install as a Cake Tool

<div align="center">

MASA.Lingua

A lightweight i18n platform: manage translations centrally, ship them as static JSON bundles, and hot-update every client over SSE.

License CI NuGet .NET

English | 简体中文

</div>


MASA.Lingua is a translation management platform plus a set of client SDKs. Editors work in a Blazor admin UI (with optional AI-assisted translation); clients — ASP.NET Core, Blazor, MAUI, and Vue 3 apps — consume published translation bundles through plain HTTP with strong ETags, and receive publish notifications over Server-Sent Events.

No runtime dependencies on the platform: after startup, clients read versioned static JSON from disk-level caching. If the Lingua server is briefly unavailable, your app keeps rendering the translations it already has.

Features

  • Static bundles with strong ETags — publishing produces immutable {culture}.json files served with ETag + Cache-Control: no-cache; unchanged requests get 304. No stale caches, no extra publish-to-client latency.
  • Hot updates over SSE — every publish event carries projectCode, per-culture ETags and versionHash; clients skip unchanged cultures and reconcile on a fixed idle interval even if an event is missed.
  • Layered fallback — global shared namespaces (common / errors) merge with per-project namespaces; unpublished translations fall back to the source culture.
  • AI-assisted translation — batch translation through Microsoft.Extensions.AI (any OpenAI-compatible endpoint, e.g. local Ollama), with deterministic validation before results are accepted.
  • Glossary enforcement — mandatory terms are validated on entry and at publish time, with compliance reporting.
  • Deterministic publishing — bundle bytes and ETags are reproducible: the same input always yields the same output, and a server restart restores published bundles byte-for-byte from database snapshots.
  • Missing-key telemetry — server-side SDKs report missing keys back to the platform (authenticated with project write keys).
  • Multi-end SDKs — IStringLocalizer for ASP.NET Core, I18n.T bridge for MASA Framework, T() for Masa.Blazor, hot-reloading localizer for .NET MAUI, and a Vue 3 adapter with a lingua-sync CLI for build-time pulls, imports and CI checks.

How it works

flowchart LR
    Editor["Admin UI (Blazor, SSO)"] -->|"edit / import / AI translate"| DB[(PostgreSQL)]
    DB -->|"publish"| Compiler["BundleCompiler<br/>deterministic build + SHA-256 ETag"]
    Compiler --> Snapshot["Publish snapshot"]
    Snapshot --> Disk["Static {culture}.json"]
    Disk -->|"HTTP GET, ETag / 304"| Clients["ASP.NET Core / Blazor / MAUI / Vue"]
    Compiler -->|"publish event"| SSE["SSE stream"]
    SSE -->|"changed cultures"| Clients
    Clients -->|"missing keys (server SDKs)"| DB

Packages

Package Target Description
MASA.Lingua.Core net8.0 / net10.0 Domain model, bundle compiler, JSON converter, deterministic validation engine
MASA.Lingua.SDK.Abstractions net8.0 / net10.0 Client contracts, frozen memory store, sync protocol
MASA.Lingua.SDK.AspNetCore net8.0 / net10.0 IStringLocalizer adapter backed by {culture}.json, SSE + polling hot reload
MASA.Lingua.SDK.MasaI18n net8.0 / net10.0 Bridge into MASA Framework I18n.T / II18n<T>
MASA.Lingua.SDK.MasaBlazor net8.0 / net10.0 Masa.Blazor T() integration
MASA.Lingua.SDK.Maui net8.0 / net10.0 Localizer for .NET MAUI / Blazor Hybrid / WPF clients
@lingua/vue Node >= 18 Vue 3 + vue-i18n adapter, plus the lingua-sync CLI (pull / push / check)

The server itself (MASA.Lingua.Server, .NET 10) and the EF Core storage are not published as packages — deploy the Docker image instead.

Quick start

Full walkthrough: docs/quickstart.md. The admin UI requires SSO login, but everything below works through the anonymous machine API — no SSO needed.

# 1. PostgreSQL (the only supported database)
docker run -d --name lingua-pg -e POSTGRES_PASSWORD=lingua -e POSTGRES_DB=lingua -p 5432:5432 postgres:16

# 2. Lingua server (dev run; Auth__Authority override skips the MASA Stack DCC/SSO lookup)
dotnet run --project src/MASA.Lingua.Server -- \
  Lingua__Database__ConnectionString="Server=localhost;Port=5432;User Id=postgres;Password=lingua;Database=lingua;" \
  Auth__Authority=https://sso.invalid \
  Auth__ClientId=local
# 3. Create a project, import a draft, publish it
curl -X POST http://localhost:62641/api/v1/projects/demo

curl -X POST "http://localhost:62641/api/v1/projects/demo/import-json?culture=en-US&publish=true" \
  -H "Content-Type: application/json" \
  -d '{"greeting": "Hello, {name}!"}'
// 4. Consume it from any ASP.NET Core app (net8.0 / net10.0)
builder.Services.AddLinguaLocalization(options =>
{
    options.ServerEndpoint = "http://localhost:62641";
    options.ProjectCode = "demo";
});

A first-boot empty database is seeded with three demo projects (auth-web-staging, auth-sso-staging, shop-vue) you can explore immediately.

Client integration matrix

Client type Package / tool Hot update
ASP.NET Core (MVC / Minimal API / Razor Pages) MASA.Lingua.SDK.AspNetCore SSE + polling fallback, automatic
MASA Framework I18n (I18n.T) MASA.Lingua.SDK.MasaI18n Real-time after publish, zero call-site changes
Masa.Blazor frontend MASA.Lingua.SDK.MasaBlazor Shared store with SSE reconcile when co-hosted with MasaI18n
.NET MAUI / Blazor Hybrid / WPF MASA.Lingua.SDK.Maui Syncs at startup and on resume
Vue 3 + vue-i18n @lingua/vue SSE + polling, startHotUpdate()
Build time (CI checks, bulk import/export) lingua-sync CLI —

Per-client guides live in docs/integration.

Deployment notes

  • Runtime: .NET 10 for the server; PostgreSQL only; single instance (publish cache and SSE broadcast are in-process state — scaling out requires externalizing them first).
  • HTTPS required for the admin UI (OIDC cookies are Secure); terminate TLS at your ingress and set ASPNETCORE_FORWARDEDHEADERS_ENABLED=true.
  • Machine-facing read endpoints are anonymous and CORS-open — deploy on a trusted network; write endpoints and the admin UI have separate controls. Details: docs/deployment.md.

Documentation

  • Quick start — from empty database to a translated, published, consumed string
  • Architecture — components and data flow
  • Deployment — production checklist: HTTPS, persistence, resource limits
  • Integration guides — per-client SDK guides with verified examples

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and pull request guidelines. Please read our Code of Conduct and note the security policy for reporting vulnerabilities.

License

This project is licensed under the Apache License 2.0.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on MASA.Lingua.SDK.AspNetCore:

Package Downloads
MASA.Lingua.SDK.MasaI18n

Bridge adapter between MASA.Lingua SDK and MASA.Framework I18n (II18n / I18n.T). Wires the hot-reloading Lingua memory store into MASA's II18nResourceContributor pipeline, so existing I18n.T call sites pick up published translations without any code change.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.0.1-preview.3 43 11/13/2026
0.0.1-preview.2 50 11/12/2026
0.0.1-preview.1 85 11/9/2026