Localization.md

Localization in Prometheus

This project uses a centralized localization system so UI strings are not scattered across tools.

Current status

• Infrastructure: implemented
• Locale auto-detection: implemented (machine locale)
• Fallback behavior: implemented (requested -> language -> en)
• Default catalog: English (en)
• Additional locales: Greek (el)

Centralized architecture

• Shared localization core: src/shared/localization/index.ts
• Base English catalog: src/shared/localization/catalog.en.ts
• Main shell, tools, and Bun runtime messages all read from the same localization module.
• No tool-local locale files are used.

Locale resolution behavior

At startup, Prometheus resolves locale in this order:

1. Machine locale (browser/runtime)
2. Language-only fallback (for example pt-BR -> pt)
3. English fallback (en)

If a key is missing in a non-English locale, Prometheus falls back to English for that key.

How to add a new language

1. Add a new locale catalog in src/shared/localization/ (for example catalog.es.ts).
2. Include all keys that exist in catalog.en.ts.
3. Register the locale in src/shared/localization/index.ts in CATALOG_BY_LOCALE and SUPPORTED_LOCALES.
4. Run validation:
   • bunx tsc --noEmit
   • bun run build:dev
5. Run app smoke check:
   • bun run start
   • verify menu labels, tool buttons, modal text, and repeated runtime status strings.

Key naming conventions

• Use domain-first keys:
  • common.*
  • view.menu.*
  • view.content.*
  • settings.*
  • modal.*
  • runtime.*
• Prefer explicit key names over generic names.
• Reuse existing shared keys for repeated strings (buttons, status labels, common warnings).

Contribution guidelines for translators

• Keep meaning and tone practical and concise.
• Preserve placeholders exactly (for example {count}, {error}, {runtime_os}).
• Do not change key names in code.
• If wording is unclear in English, open an issue/PR note and propose improved source copy.