phrasebook

import "git.golem15.com/golem15/summercms/modules/phrasebook"

Overview#

phrasebook owns every translatable string in a SummerCMS application. At boot, phrasebook.Activate loads the framework's own strings plus the lang/ tree of every plugin that implements pact.HasLang, applies overrides from plugins that implement pact.HasLangOverrides, and publishes a single phrasebook.Translator on the backpack.App. Keys use the WinterCMS form namespace::group.dot.path, and message syntax follows Laravel (:name placeholders, | plural pipes), so it is the counterpart of WinterCMS's Lang::get / trans_choice and plugin lang/ directories.

Features#

• YAML catalogs laid out as lang/<locale>/<group>.yaml; nested maps flatten into keys such as acme.blog::posts.title (phrasebook.Catalog.Load). Duplicate keys, duplicate namespaces, malformed paths and non-string leaves fail at load time.
• Overrides laid out as lang/<locale>/<namespace>/<group>.yaml that replace keys of any loaded namespace, including the framework admin strings, and may add locales (phrasebook.Catalog.Override).
• Built-in framework namespaces: lagoon::validate.* (validation messages) and backend::lang.* (admin UI strings), shipped for en and pl.
• Lookups by request locale (phrasebook.Translator.Get, read from the context through towel.Locale) or by explicit locale (phrasebook.Translator.GetIn), walking the locale, its parent tags (pt-BR to pt) and then the fallback locale. A missing key returns the key itself.
• Laravel-style placeholders: :name, :Name (first letter upper-cased) and :NAME (upper-cased).
• Pluralization with phrasebook.Translator.Choice and phrasebook.Translator.ChoiceIn: CLDR plural maps (one, few, many, other, ...) validated against the locale's categories, or Laravel pipes with exact ({0}) and range ([2,*]) conditions. :count is filled in automatically.
• Export for the admin SPA: phrasebook.Translator.Forms returns a key as CLDR plural forms, phrasebook.Translator.Bundle returns every key under a prefix, and phrasebook.Translator.Resolved reports which locale such a bundle mostly comes from. Activation fails if a backend:: string cannot be expressed as CLDR forms.
• Missing keys are logged once per key through log/slog, except in the production environment.

Usage#

Plugins normally only ship a lang/ tree and implement pact.HasLang; the runtime calls phrasebook.Activate and handlers look the translator up from the app. A catalog can also be built directly:

# lang/en/posts.yaml
title: Posts
greeting: "Hello, :name"
count:
  one: ":count post"
  other: ":count posts"

package blog

import (
	"context"
	"embed"
	"fmt"

	"git.golem15.com/golem15/summercms/modules/backpack"
	"git.golem15.com/golem15/summercms/modules/phrasebook"
	"git.golem15.com/golem15/summercms/modules/towel"
)

//go:embed lang
var langFS embed.FS

func Example() error {
	cat := phrasebook.NewCatalog()
	if err := cat.Load("acme.blog", langFS); err != nil {
		return err
	}
	tr := phrasebook.NewTranslator(cat, phrasebook.Options{Locale: "en", Fallback: "en"})

	ctx := towel.WithLocale(context.Background(), "en")
	fmt.Println(tr.Get(ctx, "acme.blog::posts.greeting", map[string]string{"name": "Ada"})) // Hello, Ada
	fmt.Println(tr.ChoiceIn("en", "acme.blog::posts.count", 3, nil))                         // 3 posts
	return nil
}

// Inside a running application, use the translator published at boot.
func Title(ctx context.Context, app *backpack.App) string {
	tr, ok := app.Lookup[*phrasebook.Translator]()
	if !ok {
		return "acme.blog::posts.title"
	}
	return tr.Get(ctx, "acme.blog::posts.title", nil)
}

API reference#

Configuration#

phrasebook.Activate reads these keys from the app's compass config:

When the compass environment is production, missing-key warnings are not logged.

Dependencies#

• SummerCMS modules: backpack, pact, towel.
• Third-party: github.com/goccy/go-yaml, github.com/nicksnyder/go-i18n/v2 (CLDR plural rules), golang.org/x/text/language.
• Standard library: context, embed, fmt, io/fs, log/slog, path, regexp, sort, strconv, strings, sync, unicode, unicode/utf8.

Testing#

go test ./modules/phrasebook/...

The tests use in-memory filesystems and need no external services.