Logging and Localization

Logging and localization are both cross-boundary product systems in Sambee.

• Logging affects local debugging, operator visibility, and backend trace collection.
• Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.

Treat both as shared contracts rather than optional polish.

Logging Model

Sambee uses more than one logging surface, but the goal is still one coherent diagnostic story.

Backend Logging

The backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the [app] section of config.toml:

[app]
log_level = "INFO"
access_log_level = "WARNING"
protocol_log_level = "WARNING"

All three settings accept DEBUG, INFO, WARNING, or ERROR, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.

Set access_log_level to INFO when request auditing is needed. Set protocol_log_level to DEBUG only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.

Browser App Logging

The browser app supports both:

• Console logging for local development and debugging.
• Backend tracing for server-side log collection when production or mobile debugging needs it.

That means a logging change can affect both developer ergonomics and support visibility.

Companion and Service-Side Logging

The companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.

• Use the shared logging utilities where the app already has them.
• Keep log messages specific enough to be actionable.
• Avoid replacing structured or filtered logging with scattered ad hoc output.

For local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.

Localization Model

Localization is a typed system, not just a string file.

Sources of Truth

English is the source locale, and the pseudo-locale is generated automatically from the English tree.

Contributor Rules

• Add new UI strings through the translation resources instead of hard-coding copy.
• Keep translation keys type-safe instead of casting around the type system.
• Preserve the distinction between UI language and regional formatting behavior.
• Remember that the browser app can push its effective locale into the companion through the paired localhost API.

What Contributors Must Preserve

Logging

• Browser app logging and backend tracing are related but separately configurable.
• Logging changes should not silently remove trace visibility that support workflows depend on.
• Diagnostics should stay specific and action-oriented.

Localization

• Typed keys should remain enforced.
• Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.
• App-owned UI text should stay translatable.

For the concrete contributor workflow, continue to Localization and Locale Behavior .

Common Failure Modes

• Adding UI text without a translation key.
• Bypassing typed translation keys with casts.
• Changing localization behavior in the browser app without checking companion sync effects.
• Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.
• Flooding logs with noisy messages that hide the actionable ones.

Validation Expectations

When this area changes, usually run:

cd frontend && npx tsc --noEmit
cd frontend && npm run lint
cd companion && npx tsc --noEmit
cd companion && npm run lint

For higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.

Use Test Strategy Overview to decide when those cross-boundary checks need to extend further.