Design daw_i18n/v1 text override for host programs

michael commented

2026-08-14 13:19:46 +02:00

Owner

Goal

Design how a host program can override a daw_i18n/v1 text
(from a library or module) with its own text for a given resource_id.

Background

Raised while deciding DAW/daw-lua-common#47 (i18n resource file
location). Text override is a special case of the still-open
daw_i18n/v1 discovery/collection question (deliberately kept out of
the daw_i18n/v1 contract itself) and belongs into the same
architecture work as language selection/loading in berhtjan-core.

Scope

How a host declares an override for a specific resource_id
Where override files live and how they are loaded relative to the
library/module's own i18n/ resources
Interaction with source_hash staleness detection

DAW/daw-lua-common#47

## Goal Design how a host program can override a daw_i18n/v1 text (from a library or module) with its own text for a given resource_id. ## Background Raised while deciding DAW/daw-lua-common#47 (i18n resource file location). Text override is a special case of the still-open daw_i18n/v1 discovery/collection question (deliberately kept out of the daw_i18n/v1 contract itself) and belongs into the same architecture work as language selection/loading in berhtjan-core. ## Scope - How a host declares an override for a specific resource_id - Where override files live and how they are loaded relative to the library/module's own i18n/ resources - Interaction with source_hash staleness detection ## Related DAW/daw-lua-common#47

michael added the

coordination/cross-repo

labels

2026-08-14 13:19:46 +02:00

michael referenced this issue from DAW/daw-lua-common

2026-08-14 13:21:08 +02:00

Decide daw_i18n/v1 resource file location for daw-lua-common #47

michael commented

2026-08-14 13:22:04 +02:00

Author

Owner

Open question: whether the override mechanism belongs into berhtjan-core itself or into the adapter layer (core vs. adapter placement, analogous to the fs.handle -> fs facade pattern in daw-error-standard.md). Not decided yet -- part of the design scope of this issue.

michael referenced this issue from DAW/daw-lua-common

2026-08-16 14:31:42 +02:00

Add resource_id to all daw_error/v1 sites in daw-lua-common (en + de) #48

michael referenced this issue

2026-09-24 20:40:22 +02:00

Preserve command provenance and reject command name collisions in build_index() #16

michael referenced this issue from a commit

2026-09-24 20:46:32 +02:00

feat(i18n): switch contribution labels to daw_i18n/v1 resource identities

michael referenced this issue

2026-10-04 21:05:41 +02:00

Beschreibungsbasierte Anwendungen: Konsequenzen für Berhtjan Core prüfen #17

michael referenced this issue from a commit

2026-10-16 07:22:02 +02:00

feat(lang): per-language catalogs for resolve_resource(), add language_chain()

michael referenced this issue from a commit

2026-10-16 13:54:49 +02:00

feat(resources): add build-time logic for the per-language resource catalogs

michael referenced this issue from DAW/daw-module-manager

2026-10-16 18:02:28 +02:00

install: handle failed module-map / resource catalog regeneration after a successful install #17

michael referenced this issue from a commit

2026-10-16 18:13:20 +02:00

fix(i18n): add the schema field required by daw_i18n/v1

michael commented

2026-10-17 12:40:37 +02:00

Author

Owner

Decision summary, delivered in v2.2.0

The placement question of this issue (core or adapter) is answered:
berhtjan-core only resolves texts; it neither finds nor overrides them.

Resolution (berhtjan-core)

resolve_resource(resource_id, catalogs, languages) looks a text up in
one catalog per language and returns { text, requested_language, resolved_language, fallback_occurred }. A language of the chain
without a catalog is an error (catalog_not_loaded), never skipped.
language_chain(ctx) builds the chain: user language, then
ctx.default_lang unless identical. No implicit English.

Overrides and discovery (host, install time)

Libraries and modules ship daw_i18n/v1 sources. The host merges all
sources by configured priority, per (resource_id, language), into one
generated Lua data file per language, plus a pointer file naming the
active generation. A host override is simply a source with a higher
priority; a partial override (one language) leaves the other languages
of the resource untouched.
The default language must carry every resource; otherwise the build
aborts and the active generation stays as it is.
berhtjan-core provides the logic as pure functions
(parse_resource_source, generate_catalogs); reading the files and
activating the result is the host's job. No registry, no scope field.
The generated catalogs carry text only. source_hash staleness is a
check on the source files, not at runtime.

Not resources

Texts of user-authored definitions (reports, question catalogs, rule
messages) stay inline per language in the definition.

Open (not decided here)

What the source_hash of an override source refers to.

Delivered by 1772d38, bfff6d0 and f67c14e, released as v2.2.0 together
with daw-lua-common 2.2.0 and daw-lua-net 2.2.0. Loading in the hosts and
the berhtjan-cli migration are tracked in their own repositories.

## Decision summary, delivered in v2.2.0 The placement question of this issue (core or adapter) is answered: berhtjan-core only resolves texts; it neither finds nor overrides them. **Resolution (berhtjan-core)** - `resolve_resource(resource_id, catalogs, languages)` looks a text up in one catalog per language and returns `{ text, requested_language, resolved_language, fallback_occurred }`. A language of the chain without a catalog is an error (`catalog_not_loaded`), never skipped. - `language_chain(ctx)` builds the chain: user language, then `ctx.default_lang` unless identical. No implicit English. **Overrides and discovery (host, install time)** - Libraries and modules ship `daw_i18n/v1` sources. The host merges all sources by configured priority, per (resource_id, language), into one generated Lua data file per language, plus a pointer file naming the active generation. A host override is simply a source with a higher priority; a partial override (one language) leaves the other languages of the resource untouched. - The default language must carry every resource; otherwise the build aborts and the active generation stays as it is. - berhtjan-core provides the logic as pure functions (`parse_resource_source`, `generate_catalogs`); reading the files and activating the result is the host's job. No registry, no scope field. - The generated catalogs carry text only. `source_hash` staleness is a check on the source files, not at runtime. **Not resources** - Texts of user-authored definitions (reports, question catalogs, rule messages) stay inline per language in the definition. **Open (not decided here)** - What the `source_hash` of an override source refers to. Delivered by 1772d38, bfff6d0 and f67c14e, released as v2.2.0 together with daw-lua-common 2.2.0 and daw-lua-net 2.2.0. Loading in the hosts and the berhtjan-cli migration are tracked in their own repositories.

michael

2026-10-17 12:40:38 +02:00

closed this issue
added
status
done
and removed
status
to-go
labels

Rows
Columns

Design daw_i18n/v1 text override for host programs #13

Goal

Background

Scope

Related

Decision summary, delivered in v2.2.0