feat: release v0.26 portable i18n and presentation adapters

2026-09-29 13:31:42 +08:00
parent 6a95cad184
commit d1a747c36f
75 changed files with 5681 additions and 52 deletions
--- a/cmd/go-omni/README.md
+++ b/cmd/go-omni/README.md
@@ -1,5 +1,7 @@
 # go-omni CLI

+v0.26 新增 `i18n check|export|types|extract`：检查独立语言资源、提取 Go 静态消息引用或已导出的错误目录，导出指定命名空间的前端包和 TypeScript 类型。输入只读，结果写 stdout；动态引用明确报告。完整命令见 [国际化工具链](../../i18n/README.md#cli-提取检查与导出)。`.api errorCatalog` 可声明 translation 引用，旧 runtime 在生成前拒绝，接入时使用同版 v0.26 CLI 与框架。
+
 v0.19 移除结构映射生成：`omni.gen.json` 只保留 Repository 和中间件选项。普通接口直接使用生成 DTO；需要类型转换时用普通 Go 或可选 [copyx](../../COPY.md)。旧 `mappings` / `mappingFiles` 必须按迁移步骤清理，CLI 不会静默删除仍在调用的旧生成文件。

 公共字段组合、中间件工厂和按需 Repository 继续支持，见 [生成能力指南](../../GENERATION.md)。
@@ -14,7 +16,7 @@ v0.14 新增 `api format [--check]`、`api upgrade [--dry-run|--preview <空目

 ```sh
 # 仓库读取权限与 PATH 配置见根目录 README
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.25.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.26.0-preview
 go-omni new --module example.com/hello ./hello

 # 从自己的契约生成；service.api 及其相对 import 文件需要在本地存在
@@ -49,14 +51,14 @@ main、Gen.go、OpenAPI 和 manifest 由生成器维护；业务文件按字节

 ## 版本与迁移

-CLI 与框架依赖固定使用 v0.25.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：
+CLI 与框架依赖固定使用 v0.26.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：

 ```sh
 # 在 go-omni 源码仓库中执行
 go run ./cmd/go-omni new --module example.com/hello --framework-dir . ../hello
 ```

-当前模板与依赖以 v0.25.0-preview 为基线，继续使用 manifest v2；GORM 可选适配器从 v0.14.1-preview 提供。已有项目使用 [定点升级与预览](../../DEVELOPMENT.md#v013-项目升级)：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。
+当前模板与依赖以 v0.26.0-preview 为基线，继续使用 manifest v2；GORM 可选适配器从 v0.14.1-preview 提供。已有项目使用 [定点升级与预览](../../DEVELOPMENT.md#v013-项目升级)：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。

 ## 数据库迁移命令

--- a/cmd/go-omni/apigen/contractMetadata.go
+++ b/cmd/go-omni/apigen/contractMetadata.go
@@ -55,6 +55,7 @@ func prepareMetadata(original *Spec) (*Spec, error) {
 	for i := range spec.Errors {
 		spec.Errors[i].BusinessCode = normalized.Definitions[spec.Errors[i].Code].Code
 		spec.Errors[i].Params = normalized.Definitions[spec.Errors[i].Code].Params
+		spec.Errors[i].Translation = normalized.Definitions[spec.Errors[i].Code].Translation
 	}
 	if err := validateErrorPolicies(&spec); err != nil {
 		return nil, err
--- a/cmd/go-omni/apigen/declarations.go
+++ b/cmd/go-omni/apigen/declarations.go
@@ -11,14 +11,15 @@ import (
 // ErrorDefinition declares a public, stable error. Generated constructors return
 // a fresh error each time so WithCause cannot mutate a shared singleton.
 type ErrorDefinition struct {
-	Name         string                `json:"name"`
-	BusinessCode any                   `json:"businessCode,omitempty"`
-	Params       []apierrors.Parameter `json:"params,omitempty"`
-	Catalog      string                `json:"catalog,omitempty"`
-	Status       int                   `json:"status"`
-	Code         string                `json:"code"`
-	Message      string                `json:"message"`
-	Position     string                `json:"-"`
+	Name         string                 `json:"name"`
+	BusinessCode any                    `json:"businessCode,omitempty"`
+	Params       []apierrors.Parameter  `json:"params,omitempty"`
+	Translation  *apierrors.Translation `json:"translation,omitempty"`
+	Catalog      string                 `json:"catalog,omitempty"`
+	Status       int                    `json:"status"`
+	Code         string                 `json:"code"`
+	Message      string                 `json:"message"`
+	Position     string                 `json:"-"`
 }
 type AuthDefinition struct {
 	Name, Type, In, KeyName, Middleware, Description, BearerFormat, Position string
--- a/cmd/go-omni/apigen/errorCatalog.go
+++ b/cmd/go-omni/apigen/errorCatalog.go
@@ -49,11 +49,12 @@ func (p *parser) parseErrorCatalog() error {
 		}
 	}
 	type entry struct {
-		Key     string                `json:"key"`
-		Code    any                   `json:"code"`
-		Message string                `json:"message"`
-		Status  int                   `json:"status"`
-		Params  []apierrors.Parameter `json:"params"`
+		Key         string                 `json:"key"`
+		Code        any                    `json:"code"`
+		Message     string                 `json:"message"`
+		Status      int                    `json:"status"`
+		Params      []apierrors.Parameter  `json:"params"`
+		Translation *apierrors.Translation `json:"translation"`
 	}
 	var entries map[string]entry
 	if err := apierrors.DecodeCatalogJSON([]byte(props["errors"]), &entries); err != nil {
@@ -75,7 +76,7 @@ func (p *parser) parseErrorCatalog() error {
 		if e.Status == 0 {
 			e.Status = defaultStatus
 		}
-		p.spec.Errors = append(p.spec.Errors, ErrorDefinition{Name: fn, Status: e.Status, Code: e.Key, Message: e.Message, BusinessCode: e.Code, Params: e.Params, Catalog: name, Position: pos})
+		p.spec.Errors = append(p.spec.Errors, ErrorDefinition{Name: fn, Status: e.Status, Code: e.Key, Message: e.Message, BusinessCode: e.Code, Params: e.Params, Translation: e.Translation, Catalog: name, Position: pos})
 	}
 	return nil
 }
@@ -90,7 +91,7 @@ func errorCatalog(spec *Spec, names []string) apierrors.Catalog {
 		if names != nil && !selected[e.Name] {
 			continue
 		}
-		c.Definitions[e.Code] = apierrors.Definition{Status: e.Status, Code: e.BusinessCode, Message: e.Message, Params: e.Params}
+		c.Definitions[e.Code] = apierrors.Definition{Status: e.Status, Code: e.BusinessCode, Message: e.Message, Params: e.Params, Translation: e.Translation}
 	}
 	return c
 }
--- a/cmd/go-omni/apigen/generate.go
+++ b/cmd/go-omni/apigen/generate.go
@@ -22,7 +22,7 @@ const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"

 // Runtime-only releases need not raise the managed template compatibility floor.
 const minimumVersion = "v0.22.0-preview"
-const currentVersion = "v0.25.0-preview"
+const currentVersion = "v0.26.0-preview"
 const generatedHeader = "// Code generated by go-omni api. DO NOT EDIT.\n"

 type Options struct {
@@ -194,6 +194,13 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 		}
 		seeds["go.mod"] = data
 	}
+	capabilityModule := moduleData
+	if seeded, ok := seeds["go.mod"]; ok {
+		capabilityModule = seeded
+	}
+	if err := checkI18nRuntime(c.Spec, capabilityModule, directory); err != nil {
+		return Output{}, err
+	}
 	if err = module.CheckImportPath(o.Module); err != nil {
 		return Output{}, err
 	}
--- a/cmd/go-omni/apigen/i18nVersion.go
+++ b/cmd/go-omni/apigen/i18nVersion.go
@@ -0,0 +1,57 @@
+package apigen
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"golang.org/x/mod/modfile"
+	"golang.org/x/mod/semver"
+)
+
+// Translation metadata was introduced in this release. Consumers of older
+// runtimes must upgrade or use an explicitly supported local replacement.
+const i18nMinimumVersion = "v0.26.0-preview"
+
+func checkI18nRuntime(spec *Spec, moduleData []byte, directory string) error {
+	needed := false
+	for _, e := range spec.Errors {
+		needed = needed || e.Translation != nil
+	}
+	if !needed {
+		return nil
+	}
+	mf, err := modfile.Parse("go.mod", moduleData, nil)
+	if err != nil {
+		return err
+	}
+	version := ""
+	for _, r := range mf.Require {
+		if r.Mod.Path == frameworkModule {
+			version = r.Mod.Version
+		}
+	}
+	for _, r := range mf.Replace {
+		if r.Old.Path != frameworkModule || r.Old.Version != "" && r.Old.Version != version {
+			continue
+		}
+		if r.New.Version != "" {
+			version = r.New.Version
+			continue
+		}
+		root := r.New.Path
+		if !filepath.IsAbs(root) {
+			root = filepath.Join(directory, root)
+		}
+		data, e := os.ReadFile(filepath.Join(root, "errors", "localization.go"))
+		if e == nil && strings.Contains(string(data), "type Translation struct") {
+			return nil
+		}
+		return fmt.Errorf("translation metadata requires a local framework with errors.Translation support")
+	}
+	if semver.Compare(version, i18nMinimumVersion) < 0 {
+		return fmt.Errorf("translation metadata requires %s or newer; use --framework-dir for unpublished source", i18nMinimumVersion)
+	}
+	return nil
+}
--- a/cmd/go-omni/apigen/i18n_test.go
+++ b/cmd/go-omni/apigen/i18n_test.go
@@ -0,0 +1,42 @@
+package apigen
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestI18nTranslationMetadataAndVersionBoundary(t *testing.T) {
+	spec, err := Parse(filepath.Join(frameworkRoot(t), "examples/contracts/i18n.api"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	compiled, err := Compile(spec)
+	if err != nil {
+		t.Fatal(err)
+	}
+	ref := compiled.Spec.Errors[0].Translation
+	if ref == nil || ref.Namespace != "limits" || ref.Key != "exceeded" {
+		t.Fatal(ref)
+	}
+	if err := checkI18nRuntime(spec, []byte("module example.com/test\ngo 1.22\nrequire "+frameworkModule+" v0.25.0-preview\n"), t.TempDir()); err == nil {
+		t.Fatal("old runtime accepted")
+	}
+	generated, _, err := renderProject(Options{Module: "example.com/test"}, compiled, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(generated["internal/apierrors/errorsGen.go"]), "translation") || !strings.Contains(string(generated["docs/openapi.json"]), "translation") {
+		t.Fatal("translation metadata lost")
+	}
+	bad := readFile(t, filepath.Join(frameworkRoot(t), "examples/contracts/i18n.api"))
+	bad = strings.Replace(bad, `"namespace":"limits"`, `"namespace":""`, 1)
+	parsed, err := parseText(t, bad)
+	if err == nil {
+		_, err = Compile(parsed)
+	}
+	if err == nil {
+		t.Fatal("invalid translation reference accepted")
+	}
+}
+func TestI18nGeneratedConsumer(t *testing.T) { testCatalogConsumer(t, "i18n.api", "i18n") }
--- a/cmd/go-omni/apigen/testdata/i18n/consumer_test.go
+++ b/cmd/go-omni/apigen/testdata/i18n/consumer_test.go
@@ -0,0 +1,70 @@
+package main_test
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http/httptest"
+	"testing"
+
+	"example.com/errorCatalog/internal/apierrors"
+	"example.com/errorCatalog/internal/handler"
+	"example.com/errorCatalog/internal/svc"
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	"git.yuntuo.hk/k2safe/go-omni/httpx"
+	"git.yuntuo.hk/k2safe/go-omni/i18n"
+	"git.yuntuo.hk/k2safe/go-omni/i18n/errori18n"
+	"git.yuntuo.hk/k2safe/go-omni/i18n/httpi18n"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+func TestGeneratedTranslationAndParameterCompatibility(t *testing.T) {
+	catalog := apierrors.Catalog()
+	source, err := errori18n.Source(catalog, "en")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source = append(source, i18n.Document{Version: 1, Locale: "zh-Hans", Namespace: "limits", Messages: map[string]i18n.Message{"exceeded": {Value: i18n.Pattern{Text: "上限：{max}"}}}})
+	b, err := i18n.New(i18n.Config{SourceLocale: "en", DefaultLocale: "en", Locales: []string{"en", "zh-Hans"}}, source...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	p, err := httpi18n.New(b)
+	if err != nil {
+		t.Fatal(err)
+	}
+	lc := logx.Default()
+	lc.Writer = io.Discard
+	logger, err := logx.New(lc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+	deps, err := svc.New(context.Background(), logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer deps.Close()
+	a := omni.New(omni.WithLanguagePolicy(p), omni.WithErrorLocalizer(errori18n.New(b, nil)))
+	defer a.Close()
+	a.Use(func(next httpx.Handler) httpx.Handler {
+		return func(c *httpx.Context) error { return apierrors.LimitExceeded(9223372036854775807) }
+	})
+	if err := handler.RegisterRoutes(a, deps); err != nil {
+		t.Fatal(err)
+	}
+	r := httptest.NewRequest("GET", "/value", nil)
+	r.Header.Set("Accept-Language", "zh-CN")
+	w := httptest.NewRecorder()
+	a.ServeHTTP(w, r)
+	var body map[string]any
+	if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {
+		t.Fatal(err)
+	}
+	if w.Code != 200 || body["detail"] != "上限：9223372036854775807" || body["code"] != float64(400001) || body["ok"] != false {
+		t.Fatal(w.Code, body)
+	}
+	if apierrors.LimitExceeded(5).Message != "Limit: 5" {
+		t.Fatal("non-HTTP constructor changed")
+	}
+}
--- a/cmd/go-omni/apigen/workspaceCatalog_test.go
+++ b/cmd/go-omni/apigen/workspaceCatalog_test.go
@@ -13,7 +13,7 @@ import (

 func TestWorkspaceSharedGoCatalog(t *testing.T) {
 	root := t.TempDir()
-	writeFile(t, filepath.Join(root, "go.mod"), fmt.Sprintf("module example.com/catalogs\n\ngo 1.24.0\nrequire %s v0.15.0-preview\nreplace %s => %s\n", frameworkModule, frameworkModule, strconvQuote(frameworkRoot(t))))
+	writeFile(t, filepath.Join(root, "go.mod"), fmt.Sprintf("module example.com/catalogs\n\ngo 1.22.0\nrequire %s v0.15.0-preview\nreplace %s => %s\n", frameworkModule, frameworkModule, strconvQuote(frameworkRoot(t))))
 	writeFile(t, filepath.Join(root, "internal/apierrors/catalog.go"), `package apierrors
 import errors "git.yuntuo.hk/k2safe/go-omni/errors"
 func Catalog() errors.Catalog {return errors.Catalog{DefaultStatus:400,Definitions:map[string]errors.Definition{
--- a/cmd/go-omni/i18n.go
+++ b/cmd/go-omni/i18n.go
@@ -0,0 +1,195 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/i18n"
+	"git.yuntuo.hk/k2safe/go-omni/i18n/errori18n"
+	"git.yuntuo.hk/k2safe/go-omni/i18n/i18ntool"
+)
+
+type i18nFlags []string
+
+func (v *i18nFlags) String() string { return strings.Join(*v, ",") }
+func (v *i18nFlags) Set(s string) error {
+	if s == "" {
+		return errors.New("empty value")
+	}
+	*v = append(*v, s)
+	return nil
+}
+
+func runI18n(args []string) error { return runI18nTo(args, os.Stdout) }
+func runI18nTo(args []string, w io.Writer) error {
+	if len(args) == 0 {
+		return errors.New("expected check, export, types or extract")
+	}
+	fs := flag.NewFlagSet("i18n "+args[0], flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var resources, namespaces, goFiles i18nFlags
+	configPath := fs.String("config", "", "i18n Config JSON file")
+	locale := fs.String("locale", "", "selected/source locale")
+	catalog := fs.String("catalog", "", "exported errors.Catalog JSON (extract only)")
+	fs.Var(&resources, "resource", "resource JSON file (repeatable)")
+	fs.Var(&namespaces, "namespace", "export namespace (repeatable)")
+	fs.Var(&goFiles, "go", "Go source file (repeatable)")
+	if err := fs.Parse(args[1:]); err != nil {
+		return err
+	}
+	if fs.NArg() != 0 {
+		return errors.New("unexpected positional arguments")
+	}
+	encode := func(v any) error { e := json.NewEncoder(w); e.SetIndent("", "  "); return e.Encode(v) }
+	if args[0] == "extract" && *catalog != "" {
+		if len(goFiles) > 0 || len(resources) > 0 || *configPath != "" || len(namespaces) != 1 || *locale == "" {
+			return errors.New("catalog extraction requires --catalog, --locale and exactly one --namespace")
+		}
+		raw, err := readI18nFile(*catalog)
+		if err != nil {
+			return err
+		}
+		var c apierrors.Catalog
+		if err := apierrors.DecodeCatalogJSON(raw, &c); err != nil {
+			return err
+		}
+		docs, err := errori18n.Source(errori18n.Bind(c, namespaces[0]), *locale)
+		if err != nil {
+			return err
+		}
+		for _, doc := range docs {
+			if doc.Namespace == namespaces[0] {
+				return encode(doc)
+			}
+		}
+		return errors.New("catalog has no messages in the selected namespace")
+	}
+	if *catalog != "" {
+		return errors.New("--catalog is only supported by extract")
+	}
+	if args[0] == "extract" {
+		if len(goFiles) == 0 || len(resources) > 0 || len(namespaces) > 0 || *configPath != "" || *locale != "" {
+			return errors.New("Go extraction requires one or more --go files")
+		}
+		out := i18ntool.Extraction{References: []i18ntool.Reference{}, Findings: []i18ntool.Finding{}}
+		for _, path := range goFiles {
+			raw, err := readI18nFile(path)
+			if err != nil {
+				return err
+			}
+			result, err := i18ntool.ExtractGo(path, raw)
+			if err != nil {
+				return err
+			}
+			out.References = append(out.References, result.References...)
+			out.Findings = append(out.Findings, result.Findings...)
+		}
+		return encode(out)
+	}
+	if args[0] != "check" && args[0] != "export" && args[0] != "types" {
+		return errors.New("expected check, export, types or extract")
+	}
+	if *configPath == "" || len(resources) == 0 {
+		return errors.New("--config and at least one --resource are required")
+	}
+	data, err := readI18nFile(*configPath)
+	if err != nil {
+		return err
+	}
+	var cfg i18n.Config
+	if err := i18n.DecodeJSON(data, &cfg); err != nil {
+		return err
+	}
+	docs := []i18n.Document{}
+	total := 0
+	for _, path := range resources {
+		raw, err := readI18nFile(path)
+		if err != nil {
+			return err
+		}
+		total += len(raw)
+		if total > 4<<20 {
+			return errors.New("resources exceed 4 MiB")
+		}
+		var doc i18n.Document
+		if err := i18n.DecodeJSON(raw, &doc); err != nil {
+			return fmt.Errorf("%s: %w", path, err)
+		}
+		docs = append(docs, doc)
+	}
+	bundle, err := i18n.New(cfg, docs...)
+	if err != nil {
+		return err
+	}
+	switch args[0] {
+	case "export":
+		if len(goFiles) > 0 {
+			return errors.New("--go is only supported by check/extract")
+		}
+		return bundle.Export(w, *locale, namespaces...)
+	case "types":
+		if *locale != "" || len(goFiles) > 0 {
+			return errors.New("types does not accept --locale or --go")
+		}
+		return bundle.TypeScript(w, namespaces...)
+	case "check":
+		if *locale != "" || len(namespaces) > 0 {
+			return errors.New("check validates all configured locales and namespaces")
+		}
+		findings := bundle.Check()
+		for _, path := range goFiles {
+			raw, e := readI18nFile(path)
+			if e != nil {
+				return e
+			}
+			ex, e := i18ntool.ExtractGo(path, raw)
+			if e != nil {
+				return e
+			}
+			for _, r := range ex.References {
+				if _, ok := bundle.Schema(i18n.Ref{Namespace: r.Namespace, Key: r.Key}); !ok {
+					findings = append(findings, i18n.Diagnostic{Kind: "missing", Namespace: r.Namespace, Key: r.Key, Problem: fmt.Sprintf("referenced by %s:%d", r.File, r.Line)})
+				}
+			}
+			for _, f := range ex.Findings {
+				findings = append(findings, i18n.Diagnostic{Kind: "dynamic", Problem: fmt.Sprintf("%s:%d: %s", f.File, f.Line, f.Problem)})
+			}
+		}
+		if err := encode(findings); err != nil {
+			return err
+		}
+		if len(findings) > 0 {
+			return errors.New("internationalization checks failed")
+		}
+		return nil
+	}
+	return nil
+}
+func readI18nFile(path string) ([]byte, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	s, err := f.Stat()
+	if err != nil {
+		return nil, err
+	}
+	if !s.Mode().IsRegular() {
+		return nil, errors.New("expected a regular file")
+	}
+	b, err := io.ReadAll(io.LimitReader(f, (1<<20)+1))
+	if err != nil {
+		return nil, err
+	}
+	if len(b) > 1<<20 {
+		return nil, errors.New("file exceeds 1 MiB")
+	}
+	return b, nil
+}
--- a/cmd/go-omni/i18n_test.go
+++ b/cmd/go-omni/i18n_test.go
@@ -0,0 +1,80 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.yuntuo.hk/k2safe/go-omni/i18n"
+)
+
+func TestI18nCommandsAreReadOnlyAndCheckMissing(t *testing.T) {
+	dir := t.TempDir()
+	files := map[string]string{
+		"config.json": `{"sourceLocale":"en","defaultLocale":"en","locales":["en","fr"]}`,
+		"en.json":     `{"version":1,"namespace":"ui","locale":"en","messages":{"hello":{"params":{"type":"string"},"value":{"text":"Hello {type}"}}}}`,
+		"fr.json":     `{"version":1,"namespace":"ui","locale":"fr","messages":{"hello":{"value":{"text":"Bonjour {type}"}}}}`,
+		"use.go":      "package demo\nimport words \"git.yuntuo.hk/k2safe/go-omni/i18n\"\nvar key=words.Ref{Namespace:\"ui\",Key:\"hello\"}\n",
+	}
+	for path, data := range files {
+		if err := os.WriteFile(filepath.Join(dir, path), []byte(data), 0600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	base := []string{"--config", filepath.Join(dir, "config.json"), "--resource", filepath.Join(dir, "en.json"), "--resource", filepath.Join(dir, "fr.json")}
+	var out bytes.Buffer
+	args := append([]string{"check"}, base...)
+	args = append(args, "--go", filepath.Join(dir, "use.go"))
+	if err := runI18nTo(args, &out); err != nil || strings.TrimSpace(out.String()) != "[]" {
+		t.Fatal(err, out.String())
+	}
+	out.Reset()
+	args = append([]string{"export"}, base...)
+	args = append(args, "--locale", "fr", "--namespace", "ui")
+	if err := runI18nTo(args, &out); err != nil {
+		t.Fatal(err)
+	}
+	var pack i18n.Pack
+	if err := json.Unmarshal(out.Bytes(), &pack); err != nil || pack.Locale != "fr" || len(pack.Documents) != 2 {
+		t.Fatal(err, pack)
+	}
+	out.Reset()
+	args = append([]string{"types"}, base...)
+	args = append(args, "--namespace", "ui")
+	if err := runI18nTo(args, &out); err != nil || !strings.Contains(out.String(), `"type": string`) {
+		t.Fatal(err, out.String())
+	}
+	out.Reset()
+	if err := runI18nTo([]string{"extract", "--go", filepath.Join(dir, "use.go")}, &out); err != nil || !strings.Contains(out.String(), `"key": "hello"`) {
+		t.Fatal(err, out.String())
+	}
+	for path, want := range files {
+		got, _ := os.ReadFile(filepath.Join(dir, path))
+		if string(got) != want {
+			t.Fatal("command mutated", path)
+		}
+	}
+	out.Reset()
+	args = append([]string{"check"}, base[:4]...)
+	if err := runI18nTo(args, &out); err == nil || !strings.Contains(out.String(), "direct translation missing") {
+		t.Fatal(err, out.String())
+	}
+}
+
+func TestI18nCatalogExtractionPreservesLiteralBraces(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "errors.json")
+	if err := os.WriteFile(path, []byte(`{"definitions":{"FIXED":{"code":1,"message":"${NAME}"}}}`), 0600); err != nil {
+		t.Fatal(err)
+	}
+	var out bytes.Buffer
+	if err := runI18nTo([]string{"extract", "--catalog", path, "--namespace", "errors", "--locale", "en"}, &out); err != nil {
+		t.Fatal(err)
+	}
+	var d i18n.Document
+	if err := i18n.DecodeJSON(out.Bytes(), &d); err != nil || !d.Messages["FIXED"].Value.Literal || d.Messages["FIXED"].Value.Text != "${NAME}" {
+		t.Fatal(err, d)
+	}
+}
--- a/cmd/go-omni/main.go
+++ b/cmd/go-omni/main.go
@@ -18,6 +18,11 @@ func main() {
 	}

 	switch os.Args[1] {
+	case "i18n":
+		if err := runI18n(os.Args[2:]); err != nil {
+			fmt.Fprintln(os.Stderr, "go-omni i18n:", err)
+			os.Exit(1)
+		}
 	case "workspace":
 		if err := runWorkspace(os.Args[2:]); err != nil {
 			fmt.Fprintln(os.Stderr, "go-omni workspace:", err)
@@ -170,6 +175,7 @@ func usage() {
 	fmt.Fprintln(os.Stderr, "GoOmni project tool")
 	fmt.Fprintln(os.Stderr, "")
 	fmt.Fprintln(os.Stderr, "Usage:")
+	fmt.Fprintln(os.Stderr, "  go-omni i18n <check|export|types|extract>  Validate and export independent language resources")
 	fmt.Fprintln(os.Stderr, "  go-omni migrate [--dir migrations] [--apply] [--dsn-env GO_OMNI_DB_DSN]")
 	fmt.Fprintln(os.Stderr, "  go-omni new [--module <module>] <directory>")
 	fmt.Fprintln(os.Stderr, "  go-omni new --api <file.api> [--module <module>] <directory>")
--- a/cmd/go-omni/scaffold/version.go
+++ b/cmd/go-omni/scaffold/version.go
@@ -10,7 +10,7 @@ const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
 // Source builds can carry an unpublished VCS version (including +dirty).
 // Keep this fallback in sync with the next release; installed CLIs use their
 // downloaded module version, which also has a module checksum.
-const defaultFrameworkVersion = "v0.25.0-preview"
+const defaultFrameworkVersion = "v0.26.0-preview"

 // This target is not a claim that the release already exists. Source users
 // select a local framework checkout until the module templates are published.