[Feature Request]: Localization for notifications and GUI

[kRHYME7]

Language pack support.

While maintaining Hyprdots, someone ask me about these. Then someone asked me in HyDE too. Both issues where closed as we are only using bash and at that time it is hard to maintain! Now I kinda felt we can extend HyDE thanks to its modularity.

Recently, I came up with an idea that I think will work and doesn't break the existing scripts we have.

As of the moment I implemented translations for shaders and screenshot commands, both written with bash.

For Python it is built in so no problem with that.

How to contribute:

So here's some points we need to address.

Translating Bash's scripts notification output

Basically we will use bash's associative array. A locale file will be added eg xdg_config_home/hyde/locale/en.sh

then translations are declared by using associative arrays

declare -A _T

_T["Error"]="Wrong? lol"
_T["Shader:"]="😎"
_T["Shader reloaded:"]="yeah it reloads"

this will be sourced with bash without any drawback in execution speed!

I already added the l10n.sh when sourced injects the new send_notifs and print_log functions this triggers the translations without any perf cost.

Using Python

I don't know yet but I think it is easy lol.

Other Hardcoded Guis

That sucks but we can still kinda do it. That's why we call it language packs.
Just like themes that we externally inject to the configs.

What I have in mind --

keybindings.conf

This is PITA 🫓, however we have 2 options
.

1. provide translated keybindings.conf in the language pack. Simple as that, then will be added as a post install hook
2. The binds Are displayed using the python script so we can translate it on the go. However It assumes original keybinding.conf will not change. So I suggest to use option 1.

waybar modules

This is already posible! Modules are override-able so anyone can make a translation , put it in the language pack and inject it later!

Other config base guis

Yeah same as above

---

So for the Challenges that we might encounter, is we don't have a good config installer/restorer/injector that can cleanly uninstall those configs. Yes we can Install it to your config but how to remove it!

We have existing options but it breaks HyDE. Let's see if we can (continue to) make one.

[coderabbitai]

🔗 Related PRs

#1641 - doc: French translation for Hyprdots-to-HyDE.fr.md [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Bash l10n uses associative arrays sourced at shell init, with wrapper functions that intercept send_notifs and print_log to translate arguments before passing to originals
• Python l10n uses stdlib gettext bootstrapped in pyutils, with .mo files in the HyDE-specific locale directory
• Language packs follow the existing theme pack pattern: external repos with a .psv manifest, installed via a restore script that creates backups and tracks installed files
• Uninstallation works by reading the install manifest and restoring from backup, maintaining the clean removal requirement from the ticket

Design Choices

Design Choice 1: Locale file location hierarchy

Options Considered:

1. User locale in ~/.config/hyde/locale/, system defaults in ~/.local/share/hyde/locale/
2. Single location at ~/.config/hyde/locale/ only
3. Runtime state in ~/.local/state/hyde/locale/

Chosen Option: 1

Rationale: Follows XDG conventions and existing HyDE patterns where ~/.local/share/hyde/ holds defaults and ~/.config/hyde/ holds user overrides.

Design Choice 2: Python gettext domain and locale directory

Options Considered:

1. Use ~/.local/share/hyde/locale/ mirroring standard gettext layout
2. Use ~/.local/share/locale/ (system standard but may conflict)
3. Inline translations in Python dicts (no gettext)

Chosen Option: 1

Rationale: Keeps HyDE translations self-contained and follows the same directory hierarchy as bash locale files.

Design Choice 3: Language pack manifest format

Options Considered:

1. Use existing .psv format from restore_cfg.sh
2. Create new TOML manifest (aligns with config.toml pattern)
3. Directory convention only (no manifest, infer from structure)

Chosen Option: 1

Rationale: Reuse .psv format for consistency with existing restore_cfg.sh infrastructure, avoiding new tooling.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Bash Localization Infrastructure

Create the foundational l10n system for bash scripts, establishing the translation dictionary pattern, wrapper functions, and integration into the shell initialization chain.

Task 1: Create l10n.sh Core Module

Implement the bash localization module that provides translation lookup and wrapped notification/logging functions.

• Create Configs/.local/lib/hyde/l10n.sh with:
  • Declare global _T associative array for translations
  • Implement _t() lookup function: returns ${_T[$1]:-$1} (translation or original if missing)
  • Implement _send_notifs() wrapper that translates summary/body args before calling original notify-send
  • Implement _print_log() wrapper that translates badge text arguments (-stat, -crit, -warn, -err second args)
  • Store reference to original functions before overriding
  • Conditionally override send_notifs and print_log only when translations are loaded

Task 2: Create Locale Directory Structure and English Reference

Establish the locale file hierarchy and create the English reference file containing all translatable strings.

• Create directory structure in Configs/.local/share/hyde/locale/
• Create Configs/.local/share/hyde/locale/en.sh as the reference locale containing:
  • All notification strings from shaders.sh, screenshot.sh, cliphist.sh, batterynotify.sh, animations.sh, font.sh, app2unit.sh
  • All print_log badge strings identified in exploration (error, added, skipped, etc.)
  • Comments grouping strings by source script for maintainability
• Create Configs/.config/hyde/locale/ directory placeholder for user overrides
• Add locale directory entries to Scripts/restore_cfg.psv using P flag (populate if missing)

Task 3: Integrate l10n into Shell Initialization

Hook the l10n system into globalcontrol.sh so translations load automatically for all HyDE scripts.

• Modify Configs/.local/lib/hyde/globalcontrol.sh:
  • Add locale loading logic after export_hyde_config() call
  • Source l10n.sh from $LIB_DIR/hyde/l10n.sh
  • Implement locale resolution: check $HYDE_LOCALE env var, then $LANG, default to "en"
  • Source user locale from $XDG_CONFIG_HOME/hyde/locale/$locale.sh if exists, else fall back to $XDG_DATA_HOME/hyde/locale/$locale.sh
  • Only activate translation wrappers if locale file was successfully sourced
• Add HYDE_LOCALE configuration option to Configs/.local/share/hyde/schema/schema.toml under a new [locale] section

🤖 Prompt for AI agents

Implement the bash localization infrastructure for HyDE. The goal is to create a
translation system using bash associative arrays that integrates automatically
into the existing shell initialization chain.

**Task 1: Create `Configs/.local/lib/hyde/l10n.sh`**
- Declare a global `_T` associative array for storing translations
- Implement `_t()` lookup function returning `${_T[$1]:-$1}` (falls back to
original string if no translation found)
- Implement `_send_notifs()` wrapper that translates the summary and body
arguments before calling the original `notify-send`
- Implement `_print_log()` wrapper that translates badge text arguments for
`-stat`, `-crit`, `-warn`, `-err` flags (second args)
- Store references to the original `send_notifs` and `print_log` functions
before overriding
- Conditionally override `send_notifs` and `print_log` only when translations
are loaded

**Task 2: Create locale directory structure and English reference**
- Create `Configs/.local/share/hyde/locale/` directory
- Create `Configs/.local/share/hyde/locale/en.sh` as the reference locale file:
- Include all notification strings sourced from: shaders.sh, screenshot.sh,
cliphist.sh, batterynotify.sh, animations.sh, font.sh, app2unit.sh
  - Include all `print_log` badge strings (e.g., error, added, skipped, etc.)
  - Group strings by source script using comments for maintainability
- Create `Configs/.config/hyde/locale/` directory placeholder for user overrides
- Add locale directory entries to `Scripts/restore_cfg.psv` using the `P` flag
(populate if missing)

**Task 3: Integrate l10n into `Configs/.local/lib/hyde/globalcontrol.sh`**
- After the `export_hyde_config()` call, add locale loading logic:
  - Source `l10n.sh` from `$LIB_DIR/hyde/l10n.sh`
  - Resolve locale using: `$HYDE_LOCALE` env var → `$LANG` → default `"en"`
- Source user locale from `$XDG_CONFIG_HOME/hyde/locale/$locale.sh` if it
exists, otherwise fall back to `$XDG_DATA_HOME/hyde/locale/$locale.sh`
- Activate translation wrappers only if the locale file was successfully sourced
- Add a `HYDE_LOCALE` configuration option to
`Configs/.local/share/hyde/schema/schema.toml` under a new `[locale]` section

Phase 2: Python Localization Infrastructure

Implement gettext-based internationalization for Python scripts, with a centralized bootstrap and .pot template for translators.

Task 1: Bootstrap gettext in Python Utilities

Add gettext initialization to the shared Python infrastructure so all scripts automatically have translation support.

• Create Configs/.local/lib/hyde/pyutils/i18n.py module with:
  • Function to initialize gettext with domain "hyde" and localedir pointing to $XDG_DATA_HOME/hyde/locale
  • Export _() function for use by other modules
  • Handle missing locale gracefully (fall back to passthrough)
  • Support HYDE_LOCALE environment variable override
• Modify Configs/.local/lib/hyde/pyutils/logger.py to import and initialize i18n at module load
• Create Configs/.local/share/hyde/locale/ directory structure for gettext: {locale}/LC_MESSAGES/hyde.mo

Task 2: Add Translation Markers to Python Scripts

Mark user-facing strings in key Python scripts for translation.

• Update Configs/.local/lib/hyde/waybar.py:
  • Import _ from pyutils.i18n
  • Wrap notify.send() body arguments with _()
  • Wrap rofi prompt strings (-p arguments) with _()
• Update Configs/.local/lib/hyde/pyutils/pip_env.py:
  • Wrap notification strings with _()
• Update Configs/.local/lib/hyde/keybinds/hint-hyprland.py:
  • Add standalone gettext initialization (no pyutils dependency)
  • Wrap touch edge labels and error messages with _()

Task 3: Create POT Template and English PO File

Generate the translation template for Python strings.

• Create Configs/.local/share/hyde/locale/hyde.pot containing all marked strings
• Create Configs/.local/share/hyde/locale/en/LC_MESSAGES/hyde.po as English reference
• Document the extraction process (using xgettext) in locale/README.md for contributors

🤖 Prompt for AI agents

Implement gettext-based Python localization infrastructure for HyDE. The goal is
to centralize translation bootstrapping in `pyutils` and mark user-facing
strings in key Python scripts.

**Task 1: Create `Configs/.local/lib/hyde/pyutils/i18n.py`**
- Implement a function to initialize gettext with domain `"hyde"` and
`localedir` pointing to `$XDG_DATA_HOME/hyde/locale`
- Export the `_()` translation function for use by other modules
- Handle missing locale gracefully by falling back to a passthrough function
- Support the `HYDE_LOCALE` environment variable as an override
- Modify `Configs/.local/lib/hyde/pyutils/logger.py` to import and initialize
`i18n` at module load
- Create the gettext directory structure `{locale}/LC_MESSAGES/hyde.mo` under
`Configs/.local/share/hyde/locale/`

**Task 2: Add translation markers to Python scripts**
- In `Configs/.local/lib/hyde/waybar.py`: import `_` from `pyutils.i18n`, wrap
`notify.send()` body arguments and rofi `-p` prompt strings with `_()`
- In `Configs/.local/lib/hyde/pyutils/pip_env.py`: wrap notification strings
with `_()`
- In `Configs/.local/lib/hyde/keybinds/hint-hyprland.py`: add standalone gettext
initialization (no pyutils dependency), wrap touch edge labels and error
messages with `_()`

**Task 3: Create POT template and English PO file**
- Create `Configs/.local/share/hyde/locale/hyde.pot` containing all marked
translatable strings
- Create `Configs/.local/share/hyde/locale/en/LC_MESSAGES/hyde.po` as the
English reference
- Create `Configs/.local/share/hyde/locale/README.md` documenting the xgettext
extraction process for contributors

Phase 3: Language Pack System

Create the infrastructure for distributing, installing, and cleanly removing language packs.

Task 1: Define Language Pack Structure

Establish the standard structure and manifest format for language packs.

• Document language pack structure (to be placed in language pack repos):

  langpack-{locale}/
  ├── restore_lang.psv          # Manifest using restore_cfg.sh format
  ├── locale/
  │   └── {locale}.sh           # Bash translations
  ├── LC_MESSAGES/
  │   └── hyde.mo               # Compiled Python translations
  ├── keybindings.conf          # Optional: translated keybindings
  └── waybar/
      └── modules/              # Optional: translated waybar modules
  

• Define restore_lang.psv format following existing .psv conventions with paths relative to language pack root
• Create Configs/.local/share/hyde/locale/README.md documenting the structure and contribution process

Task 2: Create Language Pack Installer

Implement the installation mechanism that integrates with existing restore infrastructure.

• Create Scripts/restore_lang.sh (or extend hyde-shell with hyde-shell lang install):
  • Accept language pack directory or git URL as argument
  • Clone/fetch pack if URL provided (following themepatcher.sh pattern)
  • Create timestamped backup directory under ~/.config/cfg_backups/lang_*
  • Record installed files to ~/.local/state/hyde/langpack_manifest for uninstall tracking
  • Call restore_cfg.sh with the pack's restore_lang.psv and pack directory as source
  • Set HYDE_LOCALE in ~/.local/state/hyde/config to activate the locale
• Add installation entries to Scripts/restore_cfg.psv for the restore_lang.sh script itself

Task 3: Create Language Pack Uninstaller

Implement clean removal that restores original files.

• Extend Scripts/restore_lang.sh with --uninstall flag (or hyde-shell lang remove):
  • Read ~/.local/state/hyde/langpack_manifest to identify installed files
  • Remove language pack files from their installed locations
  • Restore original files from the backup created during install
  • Clear HYDE_LOCALE from ~/.local/state/hyde/config
  • Remove the manifest file
• Handle edge case: backup missing (warn user, offer to remove files anyway)
• Handle edge case: different language pack installed over another (chain of backups)

Task 4: Update hydectl with Locale Commands

Expose language pack management through the hydectl interface.

• Modify Configs/.local/bin/hydectl to add locale subcommands:
  • hydectl locale install <pack-path-or-url> — install a language pack
  • hydectl locale remove — uninstall current language pack
  • hydectl locale list — list available/installed locales
  • hydectl locale set <locale> — switch active locale (for packs already installed)
• Add help text and command documentation to hydectl

🤖 Prompt for AI agents

Implement the language pack distribution, installation, and removal system for
HyDE, following the existing theme pack pattern.

**Task 1: Define language pack structure**
- Create `Configs/.local/share/hyde/locale/README.md` documenting the standard
language pack layout:
- `langpack-{locale}/restore_lang.psv` — manifest using restore_cfg.sh `.psv`
format
  - `langpack-{locale}/locale/{locale}.sh` — bash translations
  - `langpack-{locale}/LC_MESSAGES/hyde.mo` — compiled Python translations
  - Optional: `keybindings.conf`, `waybar/modules/`
- Document `restore_lang.psv` format with paths relative to the language pack
root, following existing `.psv` conventions

**Task 2: Create `Scripts/restore_lang.sh` (installer)**
- Accept a language pack directory or git URL as argument
- If a URL is provided, clone/fetch the pack following the `themepatcher.sh`
pattern
- Create a timestamped backup directory under `~/.config/cfg_backups/lang_*`
- Record all installed files to `~/.local/state/hyde/langpack_manifest` for
uninstall tracking
- Call `restore_cfg.sh` with the pack's `restore_lang.psv` and the pack
directory as source
- Set `HYDE_LOCALE` in `~/.local/state/hyde/config` to activate the new locale
- Add installation entries to `Scripts/restore_cfg.psv` for the
`restore_lang.sh` script itself

**Task 3: Extend `Scripts/restore_lang.sh` with `--uninstall` flag**
- Read `~/.local/state/hyde/langpack_manifest` to identify installed files
- Remove language pack files from their installed locations
- Restore original files from the backup created during install
- Clear `HYDE_LOCALE` from `~/.local/state/hyde/config`
- Remove the manifest file
- Handle edge cases:
  - Backup missing: warn the user and offer to remove files anyway
  - Different language pack installed over another: handle the chain of backups

**Task 4: Modify `Configs/.local/bin/hydectl`**
- Add a `locale` subcommand group with:
  - `hydectl locale install <pack-path-or-url>` — install a language pack
  - `hydectl locale remove` — uninstall the current language pack
  - `hydectl locale list` — list available/installed locales
- `hydectl locale set <locale>` — switch active locale for already-installed
packs
- Add help text and command documentation for all new subcommands

Research

Codebase Summary

HyDE is a Hyprland desktop environment with configuration managed through bash scripts and Python utilities. Shell scripts source globalcontrol.sh (via hyde-shell init or direct source) which exports send_notifs() as a thin notify-send wrapper. Terminal logging uses print_log() from global_fn.sh. The export_hyde_config() function in globalcontrol.sh sources user files from ~/.local/state/hyde/, providing a natural injection point. Python GUI scripts (waybar.py, hint-hyprland.py) live in ~/.local/lib/hyde/ with shared utilities in pyutils/. Configuration deployment uses restore_cfg.sh with .psv manifests, and theme injection via themepatcher.sh demonstrates the pattern for external pack installation.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the bash localization infrastructure for HyDE. The goal is to create a
translation system using bash associative arrays that integrates automatically
into the existing shell initialization chain.

**Task 1: Create `Configs/.local/lib/hyde/l10n.sh`**
- Declare a global `_T` associative array for storing translations
- Implement `_t()` lookup function returning `${_T[$1]:-$1}` (falls back to
original string if no translation found)
- Implement `_send_notifs()` wrapper that translates the summary and body
arguments before calling the original `notify-send`
- Implement `_print_log()` wrapper that translates badge text arguments for
`-stat`, `-crit`, `-warn`, `-err` flags (second args)
- Store references to the original `send_notifs` and `print_log` functions
before overriding
- Conditionally override `send_notifs` and `print_log` only when translations
are loaded

**Task 2: Create locale directory structure and English reference**
- Create `Configs/.local/share/hyde/locale/` directory
- Create `Configs/.local/share/hyde/locale/en.sh` as the reference locale file:
- Include all notification strings sourced from: shaders.sh, screenshot.sh,
cliphist.sh, batterynotify.sh, animations.sh, font.sh, app2unit.sh
  - Include all `print_log` badge strings (e.g., error, added, skipped, etc.)
  - Group strings by source script using comments for maintainability
- Create `Configs/.config/hyde/locale/` directory placeholder for user overrides
- Add locale directory entries to `Scripts/restore_cfg.psv` using the `P` flag
(populate if missing)

**Task 3: Integrate l10n into `Configs/.local/lib/hyde/globalcontrol.sh`**
- After the `export_hyde_config()` call, add locale loading logic:
  - Source `l10n.sh` from `$LIB_DIR/hyde/l10n.sh`
  - Resolve locale using: `$HYDE_LOCALE` env var → `$LANG` → default `"en"`
- Source user locale from `$XDG_CONFIG_HOME/hyde/locale/$locale.sh` if it
exists, otherwise fall back to `$XDG_DATA_HOME/hyde/locale/$locale.sh`
- Activate translation wrappers only if the locale file was successfully sourced
- Add a `HYDE_LOCALE` configuration option to
`Configs/.local/share/hyde/schema/schema.toml` under a new `[locale]` section
===============================================================================

Task: 2

Implement gettext-based Python localization infrastructure for HyDE. The goal is
to centralize translation bootstrapping in `pyutils` and mark user-facing
strings in key Python scripts.

**Task 1: Create `Configs/.local/lib/hyde/pyutils/i18n.py`**
- Implement a function to initialize gettext with domain `"hyde"` and
`localedir` pointing to `$XDG_DATA_HOME/hyde/locale`
- Export the `_()` translation function for use by other modules
- Handle missing locale gracefully by falling back to a passthrough function
- Support the `HYDE_LOCALE` environment variable as an override
- Modify `Configs/.local/lib/hyde/pyutils/logger.py` to import and initialize
`i18n` at module load
- Create the gettext directory structure `{locale}/LC_MESSAGES/hyde.mo` under
`Configs/.local/share/hyde/locale/`

**Task 2: Add translation markers to Python scripts**
- In `Configs/.local/lib/hyde/waybar.py`: import `_` from `pyutils.i18n`, wrap
`notify.send()` body arguments and rofi `-p` prompt strings with `_()`
- In `Configs/.local/lib/hyde/pyutils/pip_env.py`: wrap notification strings
with `_()`
- In `Configs/.local/lib/hyde/keybinds/hint-hyprland.py`: add standalone gettext
initialization (no pyutils dependency), wrap touch edge labels and error
messages with `_()`

**Task 3: Create POT template and English PO file**
- Create `Configs/.local/share/hyde/locale/hyde.pot` containing all marked
translatable strings
- Create `Configs/.local/share/hyde/locale/en/LC_MESSAGES/hyde.po` as the
English reference
- Create `Configs/.local/share/hyde/locale/README.md` documenting the xgettext
extraction process for contributors
===============================================================================

Task: 3

Implement the language pack distribution, installation, and removal system for
HyDE, following the existing theme pack pattern.

**Task 1: Define language pack structure**
- Create `Configs/.local/share/hyde/locale/README.md` documenting the standard
language pack layout:
- `langpack-{locale}/restore_lang.psv` — manifest using restore_cfg.sh `.psv`
format
  - `langpack-{locale}/locale/{locale}.sh` — bash translations
  - `langpack-{locale}/LC_MESSAGES/hyde.mo` — compiled Python translations
  - Optional: `keybindings.conf`, `waybar/modules/`
- Document `restore_lang.psv` format with paths relative to the language pack
root, following existing `.psv` conventions

**Task 2: Create `Scripts/restore_lang.sh` (installer)**
- Accept a language pack directory or git URL as argument
- If a URL is provided, clone/fetch the pack following the `themepatcher.sh`
pattern
- Create a timestamped backup directory under `~/.config/cfg_backups/lang_*`
- Record all installed files to `~/.local/state/hyde/langpack_manifest` for
uninstall tracking
- Call `restore_cfg.sh` with the pack's `restore_lang.psv` and the pack
directory as source
- Set `HYDE_LOCALE` in `~/.local/state/hyde/config` to activate the new locale
- Add installation entries to `Scripts/restore_cfg.psv` for the
`restore_lang.sh` script itself

**Task 3: Extend `Scripts/restore_lang.sh` with `--uninstall` flag**
- Read `~/.local/state/hyde/langpack_manifest` to identify installed files
- Remove language pack files from their installed locations
- Restore original files from the backup created during install
- Clear `HYDE_LOCALE` from `~/.local/state/hyde/config`
- Remove the manifest file
- Handle edge cases:
  - Backup missing: warn the user and offer to remove files anyway
  - Different language pack installed over another: handle the chain of backups

**Task 4: Modify `Configs/.local/bin/hydectl`**
- Add a `locale` subcommand group with:
  - `hydectl locale install <pack-path-or-url>` — install a language pack
  - `hydectl locale remove` — uninstall the current language pack
  - `hydectl locale list` — list available/installed locales
- `hydectl locale set <locale>` — switch active locale for already-installed
packs
- Add help text and command documentation for all new subcommands

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[iamharshdabas]

can i work on it?

[NahomGebeyehu]

it is still open, can i work on this one?

[Delcado19]

Picking this up after #2044/#2042 — I get the "not deterministic" objection to regex-patching live config files, and I think the fix has to be "ship whole pre-translated files, overwrite deterministically" rather than a smarter parser. Sketched out a phased plan that follows the bash-array / gettext / language-pack shape from this issue, grounded in what's actually in the repo today (file:line references, existing mechanisms to reuse, where hydectl being a binary with no source here blocks part of the original idea).

Short version:

• Phase 0: HYDE_LOCALE as a real schema/config value (mirrors HYDE_THEME), falling back to LC_ALL/LANG like today.
• Phase 1: bash catalogs (declare -A _T .sh files, sourced) — folded directly into globalcontrol.sh's real print_log/send_notifs so every caller gets translation for free, no per-script opt-in.
• Phase 2: Python via stdlib gettext (.po committed, .mo compiled at install/CI time). translate()/send() API unchanged, zero call-site churn.
• Phase 3: the actual fix for the determinism complaint — a restore_lang.sh (modeled on theme.patch.sh + restore_cfg.sh's deploy_psv "O" flag) that installs a language pack's whole pre-translated files via the same backup-then-overwrite mechanism already used for themes — no parsing at deploy time. Adds proper uninstall too (something theme packs don't have).
• Phase 4: locale switching as a standalone script, since hydectl can't be extended from this repo (compiled binary, no source here) — a hydectl locale subcommand would be a separate ask in that repo.
• Phase 5: migrate the German content from the closed feat(l10n): German (de) localization for notifications, waybar, and keybinds #2044 into this format instead of losing that translation work.

Wanted to check the shape of this against your intent before sinking time into it, given #2044/#2042 didn't land — particularly whether routing keybind/waybar translation through installable "language packs" instead of the base repo matches what you had in mind, and whether a .po+compile-at-install gettext setup is acceptable as a new toolchain dependency.

No pressure on timing — happy to wait if you're swamped, or to start with just Phase 0-1 as a small first PR if that's an easier way to de-risk this than reviewing a full design upfront. Let me know if/when you have a few minutes for this.

Full plan with file:line references and rationale

Key verified facts

• Scripts/install.sh:484 calls restore_locale.sh on every restore, not just first install — waybar/modules/* and key_binds.lua are "synced dots" that get overwritten with stock English content each time. A language pack can't be a one-shot install; it needs a reapply hook at that exact spot.
• restore_cfg.sh's deploy_psv "O" flag (~lines 176-188) already does "backup, then deterministically overwrite" (mv to BkpDir, then cp -r the new file in) — the ready-made mechanism for deploying language-pack files, no new deploy logic needed.
• theme.patch.sh is the closest existing analog to a pack installer (git URL/local dir, validation, calls into restore_cfg.sh), but has no uninstall — that needs to be built new.
• hydectl is a prebuilt Go binary with no source in this repo — extending it with locale subcommands isn't achievable from here, needs to be routed around (standalone script, same as how theme installation itself doesn't go through hydectl either).
• gettext/msgfmt/xgettext are completely absent from the repo and CI today — a genuine new toolchain dependency, though close to a non-issue on Arch in practice.
• The already-merged locale scaffolding's print_log_L/send_notifs overrides in l10n.sh have zero callers in the repo today — dead code, safe to fold away.
• tests/test_install_restore.sh already has the exact sandboxing pattern (fake $HOME, stubbed downstream scripts, assertions on a log) that new locale tests should follow.

Phase 0 — HYDE_LOCALE config plumbing

New [properties.locale]/hyde_locale section in schema.toml (same pattern as [properties.wallpaper.properties.backend]). In globalcontrol.sh, right after the existing HYDE_THEME resolve block (~lines 263-276), resolve HYDE_LOCALE: config value wins, else fall back to LC_ALL/LANG derivation like today. DESKTOP_LANG stays as the derived legacy value — no flag-day rewrite of existing detection logic needed.

Phase 1 — Bash catalogs (.sh with declare -A _T)

shutils/l10n.sh becomes a pure catalog loader (no more jq — just source the .sh file from data-home, then a config-home override). The translation logic (which today only lives in the dead print_log_L/send_notifs copy) moves directly into globalcontrol.sh's real print_log/send_notifs (lines 52-122) — so every one of the 23/18 call sites gets translation for free, with no per-script opt-in. l10n.sh gets sourced once from globalcontrol.sh instead of individually from ~20 scripts.

Catalogs get real comments for grouping (unlike JSON) — incidentally solves the de.json grouping workaround from commit 4d327ab7.

Phase 2 — Python catalogs (stdlib gettext)

pyutils/wrapper/libnotify.py: replace _load_locale_json/_load_translations with gettext.translation(domain="hyde", localedir=..., languages=[...]), using add_fallback for the config-home override tier. Public API (translate(), send()) stays unchanged — zero changes at the ~20+ call sites in python_env.py, waybar.py, window.mute.py.

New Scripts/gen-locale.sh compiles .po → .mo via msgfmt, called from install.sh and CI. Recommendation: commit .po, not .mo — .po is plain text and reviewable (the exact property missing from the JSON approach), .mo is a binary artifact with drift risk. Add gettext to CI (.github/workflows/test.yml); it's close to universally present on Arch already.

Phase 3 — Static files as language packs (replaces the regex mechanism)

The core answer to the determinism objection: no parsing, just deterministic whole-file overwrite.

restore_locale.sh: delete the waybar/XML/Lua regex-translation section (lines 227-406) entirely. The unrelated keyboard-layout-seeding and clock-format/keybind-remap sections (lines 1-225) stay untouched.

New Scripts/restore_lang.sh (modeled on theme.patch.sh + restore_cfg.sh's deploy_psv):

• install <name> <source>: load a pack from a local path or git URL, validate against a pack-supplied manifest.psv (same 4-column format restore_cfg.sh already parses, O flag throughout). Before the first deploy, snapshot every targeted file into a fixed, non-rolling location ($XDG_STATE_HOME/hyde/langpack/<name>/originals/...) — needed because BkpDir is timestamp-rolling and a second reapply would otherwise back up the pack's own already-installed file instead of the pristine original. Then call deploy_psv against the manifest — no new deploy code.
• reapply: idempotent, no re-snapshotting, called from install.sh at the exact spot restore_locale.sh is called today, so an installed pack survives every restore.
• uninstall: restore from the originals snapshot, remove the manifest/active pointer. This is the missing capability theme packs don't have today, and what this issue explicitly asks for.

A language pack can optionally bundle the Phase 1/2 catalogs too (de.sh, de.po) — one pack delivers everything for a language, not three separate artifacts.

Phase 4 — Locale switching UX (routing around hydectl)

New locale.select.sh (modeled on theme.select.sh) for interactively picking installed packs, writes to $XDG_STATE_HOME/hyde/config. hydectl can't be touched from this repo (compiled binary, no source here) — a hydectl locale subcommand would need to be a separate, later piece of work in hydectl's own repo, the same way hydectl theme today just wraps theme.select.sh/theme.switch.sh rather than reimplementing their logic in Go.

Phase 5 — Migrate the existing German translation

Split the 313 entries from the closed #2044's de.json (already grouped by feature area) into de.sh (bash call sites) and de.po (Python call sites); materialize the already-regex-translated waybar/key_binds.lua content once against a scratch checkout and turn it into static pack files. Bundle into a hyde-locale-de pack, installable via restore_lang.sh install de <path>. Retire de.json. Deliberately last — pure content migration once the mechanism exists, so review is "is the German text right" rather than "does the mechanism work."

Phase 6 — Cleanup

Remove the ~20 individual source .../l10n.sh lines from scripts that now get it for free via globalcontrol.sh — mechanical, low-risk, done last.

Verification per phase

Sandboxed tests following tests/test_install_restore.sh's pattern (fake $HOME/XDG paths, stubbed downstream scripts): test_locale_config.sh, test_l10n_bash.sh, test_l10n_python.sh, test_lang_pack.sh (install → idempotent reapply → uninstall restores original). Manual hyprctl reload + hyprctl binds -j for keybind file changes (no compositor in CI). Existing tests/*.sh suite must stay green after each phase, especially test_install_restore.sh and test_schema.sh.

[kRHYME7]

@Delcado19 thank you for understanding!

so now it looks like some of my concerns were already address

So for the Challenges that we might encounter, is we don't have a good config installer/restorer/injector that can cleanly uninstall those configs. Yes we can Install it to your config but how to remove it!

This one is handled with deez-dots. A separate repo or folder can hold a full de language pack! What I have in mind now is this language repo holds configs translations that mirror the upstream.

For Scripts:

Upstream HyDE will declare its own pot files for scripts, and we need transpiler scripts for languages that do not support .po files, example bash. So this transpiler script will be generated by maintainers and to be released as a a language pack.

For Config:

waybar

modules that are hardcoded. 2 ways I can think of.
HyDE exposes another layer of config overrides. Currently it is hyde > user

1. Override the existing modules from hyde and make the pack as the new core config
2. We can add hyde > locale > user. this way any missing modules undeclared should still work.

keybindings

This is exciting but I think we can still follow the 3 tier config we have like waybar, hyde > locale > user.

1. key_binds.lua is a script so descriptions can hold a translatable string.
2. But our concern is the WYSIWYG optimize experience for non US kb users. I think the 3tier cofig works will with this. A language pack can do overrides for the core hyde configs.

---

IMO this method is cheap for everyone of us and also maintainable. I would love to discuss more on the implementation and UX.

[kRHYME7]

Using 3 tier layer configs should make HyDE stable as any outdated packs can be just uninstalled like deez dots --uninstall language-pack-de

[kRHYME7]

about the waybar formatting I recommend this approach

This way it only touches the format and overrides it.

This should fix the waybar clock format. We can put whole translation overrides on a format and format-alt

[kRHYME7]

Will work on a us template and will need your help @NahomGebeyehu @iamharshdabas @Delcado19 if you're still interested then. Thanks! Can you tell me which part you guys want to participate?

Milestones I have in mind

1. Make pot files - python works natively I think so we can try it first on python scripts.
2. Translate to bash hash map - For bash scripts
3. Try it in lua - for lua scripts maybe we can find native runtime gettext support or use lua tables.
4. Config modules translations - this is the annoying part. But maybe some apps have easier ways to do it. At this time almost all notifs and UI will have translations except for modules.

[Delcado19]

@kRHYME7 I'll take milestone 4 (config modules — waybar .jsonc format/format-alt/tooltip-format overrides + the menu XML labels + wlogout).

One scoping question: how many languages should this milestone actually produce? I only speak German and English fluently, so I can build and verify one real language pack end-to-end (German) as the reference implementation of the override mechanism — but I don't want to guess-translate into languages I can't verify. My assumption is the milestone's deliverable is the mechanism (how a pack declares format overrides, where they live, how they get applied/uninstalled) plus one working example pack, not translations into every language at once — other languages come later from whoever actually speaks them, using the same mechanism. Let me know if you had something else in mind.

[kRHYME7]

One scoping question: ....

Our milestone targets at least having a full usable template for us. If you have the time you can contribute us and de for comparison. But what I will probably focus on is us and the whole mechanism.

[Delcado19]

@kRHYME7 Sounds good — I'll do both, us alongside your work on it (for the comparison/sanity-check) and de as the main deliverable. Will start once the mechanism/override format for config modules is settled enough to build against; happy to help iterate on that part too if useful.