projectcfg

package
v0.23.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package projectcfg loads and writes the per-project Langsync config (`.langsync.json`). It is intentionally narrow — *only* the on-disk shape and IO helpers live here; semantic decisions (what to do with a config, what's required for sync, etc.) belong in callers.

This package is scoped to the langsync service. Other services that later need their own project-level config should live under their own CLI subtree (e.g. `internal/cli/backup/projectcfg/`) so each service owns its own schema and dotfile name. There is deliberately no shared umbrella package — services stay decoupled, and one service's schema churn never touches another's file on disk.

Index

Constants

View Source
const CurrentVersion = 1

CurrentVersion is the version field written by `init`. Older configs load fine; the version is reserved for forward-incompatible changes (rename, schema reshuffle) where we'd want to refuse to load v1 from a v2 CLI without an explicit migrate step.

View Source
const Filename = ".langsync.json"

Filename is the canonical name we read and write. The CLI does not support alternate locations — the file lives at the project root, alongside go.mod / package.json / similar, and `init` plus `sync` always look for exactly this name in the current working directory (with a walk-up to find an ancestor copy, see Find).

Variables

This section is empty.

Functions

func Find

func Find(start string) (string, error)

Find walks up from start (inclusive) looking for a .langsync.json file. Returns its absolute path. Mirrors how git, npm, and similar tools find their root marker.

func Save

func Save(path string, f *File) error

Save writes the config atomically (tmp file + rename) with stable two-space indentation, the same format `init` emits.

Types

type File

type File struct {
	Version int `json:"version"`
	// Organization scopes the entire project to a specific Norcube
	// org regardless of what the CLI's persisted active_org happens
	// to be at the moment a command runs. Without it, sync would
	// silently hit whichever org the developer last ran `nrc org use`
	// against — too easy to operate on the wrong project. With it,
	// the project is self-describing.
	//
	// Optional for backwards compatibility (old configs predate
	// this field). When omitted, the CLI falls back to active_org
	// or whatever --org passes in.
	Organization *Organization `json:"organization,omitempty"`
	Namespaces   []Namespace   `json:"namespaces"`
}

File is the on-disk root document.

func Load

func Load(path string) (*File, error)

Load reads, decodes, and lightly validates a config file. It does NOT verify that namespace directories exist or that the backend namespace is still configured the same way — that's a sync-time concern.

func (*File) FindNamespace

func (f *File) FindNamespace(name string) (Namespace, bool)

FindNamespace returns the namespace entry by name (case-sensitive) and a bool for found-ness, mirroring the standard library idiom.

func (*File) ResolveDir

func (f *File) ResolveDir(configPath string, ns Namespace) string

ResolveDir returns the absolute path to ns.Dir, using configPath as the anchor for relative paths. Always use this rather than calling filepath.Abs on ns.Dir directly — the latter would silently anchor to the user's current working directory, which is wrong.

func (*File) Validate

func (f *File) Validate() error

Validate checks shape-level invariants the rest of the CLI relies on. Returns the first error encountered so the user sees a single fixable problem at a time.

type Format

type Format string

Format is the on-disk shape of translation files. Only flat-json is supported in v1 — that's what every Norcube-internal repo uses today (see ytracker-be/i18n). Add a new value (e.g. "i18next-nested", "flutter-arb") here when a project actually needs it.

const (
	FormatFlatJSON Format = "flat-json"
)

type Namespace

type Namespace struct {
	// Namespace is the URL-slug name of the Langsync namespace.
	Namespace string `json:"namespace"`
	// Dir is the directory containing one <lang-code>.<ext> file per
	// language. Relative paths are resolved against the directory the
	// config file itself lives in (NOT the user's working directory) so
	// the config is reproducible regardless of where `nrc` is invoked.
	Dir string `json:"dir"`
	// Format is how files are encoded. Only "flat-json" exists today.
	Format Format `json:"format"`
	// DefaultLocalLanguage is the code of the language the developer
	// writes marks in. Stored for reference and drift detection; sync
	// fetches the server default at runtime and errors if they diverge.
	DefaultLocalLanguage string `json:"default_local_language"`
	// LanguageAliases maps on-disk file codes to the server-side
	// language codes Langsync knows. Set automatically by the pre-flight
	// when the user resolves a "no exact match" picker (e.g. picks
	// "Map to cs-CZ" for cs_cz.json) — the entry persists so future
	// syncs auto-apply the mapping without prompting again.
	//
	// Forward (key → value): apply when reading <key>.json to decide
	// which server lang the values belong to.
	// Reverse (value → key): apply when writing pull-back results to
	// decide which filename to write to.
	//
	// Exact code matches (cs.json ↔ server "cs") don't need an alias.
	// Pure separator differences (cs_cz ↔ cs-CZ) get an automatic
	// silent alias so the file's local spelling is preserved.
	LanguageAliases map[string]string `json:"language_aliases,omitempty"`
}

Namespace ties one backend Langsync namespace to one local directory of translation files. DefaultLocalLanguage is the local file the developer edits (and that the CLI pushes from). It is derived from the namespace's backend default language at init time and re-checked on every sync so a server-side change doesn't silently desync.

type Organization

type Organization struct {
	ID   string `json:"id"`
	Slug string `json:"slug"`
	// Name is optional — kept only for display. The CLI never
	// trusts it for auth decisions.
	Name string `json:"name,omitempty"`
}

Organization is the project-pinned org identity. id is the authoritative key (immutable). slug + name are stored alongside for human display in init prompts, error messages, and code review of the JSON file — nobody wants to eyeball a UUID to know which org a project belongs to.

Directories

Path Synopsis
Package translations reads and writes language files for the sync command.
Package translations reads and writes language files for the sync command.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL