Skip to content

README.md

Latest commit

 

History

History
75 lines (53 loc) · 3.29 KB

README.md

File metadata and controls

75 lines (53 loc) · 3.29 KB
Raw
type Package Documentation
title CoreCLI i18n — translation layer
description cli.T resolution order, the CLI-local translation service (FSLoader, magic keys, template rendering), and locale registration
repo core/cli
module dappco.re/go/cli

i18n — translation layer

Translatable strings resolve through cli.T, backed by the Core i18n service with a CLI-local fallback. Command and action descriptions are i18n keys; text that is not a key passes through unchanged. Source: go/pkg/cli/i18n.go, go/pkg/i18n/i18n.go, go/pkg/cli/locales/en.json.

cli.T

label := cli.T("cmd.doctor.required")
msg := cli.T("cmd.doctor.issues", map[string]any{"Count": 3})

Resolution order:

  1. The running Core instance's i18n service (instance.core.I18n()), when initialised and its translator is OK.
  2. The CLI-local service pkg/i18n.Default().
  3. Unresolved keys return the key itself — so literal text passed to T is safe.

The CLI-local service (pkg/i18n)

A process-wide Service holds flattened key→text messages, merged from loaders:

svc := i18n.Default()
svc.AddLoader(i18n.NewFSLoader(embeddedFS, "locales"))
text := svc.T("cmd.doctor.short")
  • FSSource{FS, Dir} pairs a filesystem with a directory of locale JSON files (aliased as cli.LocaleSource).
  • FSLoader.Load(lang) reads the best matching locale file for a language from candidate names.
  • Message values render as text/template with missingkey=zero and grammar funcs (e.g. title), so {{.Count}} style placeholders work.

Magic keys

Keys with reserved prefixes compose grammar instead of requiring a catalogue entry:

Prefix Behaviour Helper
i18n.fail.<verb> "Failed to verb subject" ActionFailed(verb, subject)
i18n.done.<verb> Completed-action result —
i18n.label.<word> Label form of word Label(word)
i18n.progress.<verb> Gerund form ("Building...") Progress(verb)

The subject argument is read from a string arg or from map keys Subject/Item/Name/Value. These prefixes are what cli.WrapVerb, cli.Progress, and cli.Task compose their text through.

Locale registration

The framework's own strings ship embedded (go:embed locales/*.json in app.go, English catalogue at go/pkg/cli/locales/en.json, keys under cmd.* and i18n.*). Binaries add their own sources:

locales := cli.WithLocales(embeddedLocales, "locales")
cli.MainWithLocales([]cli.LocaleSource{locales}, addCommands)

// or per command package:
cli.WithCommands("doctor", doctor.AddDoctorCommands, doctorLocaleFS)

Grammar engine (go-i18n) — a separate module

The article-correct grammar engine ("an SSH", "a go.mod") is dappco.re/go/i18n (go-i18n), a dependency of the core binary, not of this lib. cmd/core's help generator uses it to compose readable descriptions from action names (demo.echo → "Echo the demo") — see cmd-core/. The lean lib only knows the HelpGenerator func type.

File map

File Contents
go/pkg/cli/i18n.go T with Core-service-then-local resolution; internal grammar helpers
go/pkg/i18n/i18n.go Service, Default, FSSource, FSLoader, magic keys, template rendering
go/pkg/cli/locales/en.json Framework English catalogue