New locale

AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md
+
+## What this is
+A pure GTK4 C++ GUI for remapping the G1–G9 keys of a Logitech G910. Today it
+only edits and persists mappings: there is **no** hardware G-key detection and
+**no** command execution yet (a native daemon is the planned next step). The
+whole program is one translation unit, `src/main.cpp`.
+
+## Build / run / verify
+- `make` — builds the `gkeymapper` binary **and** the `.mo` catalogs.
+  Needs `g++` (C++17), `make`, `gettext`, `libgtk-4-dev` (see README for
+  `apt install` on a fresh machine).
+- `make translations` — only runs `msgfmt` on the existing `.po` files.
+- `make run` — builds, then runs with `GKEYMAPPER_LOCALEDIR=$PWD/locale` and
+  `GKEYMAPPER_ASSETS_DIR=$PWD/assets` so the working-tree translations and
+  assets are used. Plain `./gkeymapper` works too (assets fall back to
+  `./assets`).
+- `make clean` — deletes the binary and the generated `locale/` tree.
+- No tests and no CI. Verify changes by building and running the app.
+
+## i18n — easy to get wrong
+- English is the source language (the `msgid`) **and** also has an explicit
+  identity catalog `po/en.po`. Languages: `de`, `en`, `es`, `fr`.
+- `make translations` does **not** regenerate the `.pot`. When you add or change
+  a UI string, edit `po/gkeymapper.pot` and `po/*.po` by hand, then run
+  `make translations`; validate with `msgfmt --check -o /dev/null po/<lang>.po`.
+- Never edit the generated `.mo` files under `locale/` (gitignored). Delete any
+  `po/*.po~` backups before committing.
+- All documentation and source comments are English. German appears only inside
+  `po/de.po`.
+
+## Code layout and conventions
+- `src/main.cpp` holds everything in an anonymous namespace. The global `rows`
+  vector keeps one `KeyRow` (widget pointers) per G key. `on_activate` registers
+  the app actions `app.export-config`, `app.import-config`, `app.about`;
+  `build_ui` constructs the window. App id: `com.example.gkeymapper`.
+- The Type dropdown index is meaningful everywhere: `0=Key`, `1=Command`,
+  `2=Disabled`. Keep that order — import/export map against it.
+- The capture dialog's `CaptureSession` is heap-allocated and freed only by the
+  window's `"destroy"` handler. Always close the dialog with
+  `gtk_window_destroy` so the session is released.
+- Use GTK4 API only: `gtk_editable_set_text` / `gtk_editable_get_text` (there is
+  no `gtk_entry_set_text`), `gtk_window_destroy` (no `gtk_dialog_run`),
+  `G_APPLICATION_FLAGS_NONE`.
+- The main window is intentionally **non-resizable** and has **no**
+  `GtkScrolledWindow` (one collapsed the rows earlier). Keep the fixed widths
+  (Type dropdown 150 px, target entry 440 px min, action button 180 px) so rows
+  do not jump when the language changes.
+- Because it is pure GTK4 it follows the system theme (Mint-Y ships a
+  `gtk-4.0` theme). Do **not** add the `suggested-action` CSS class — Mint-Y
+  tints it green and it clashes with the rest of the layout.
+
+## Config file format
+`Save mappings` writes `~/.config/gKeyMapper/mappings.conf`; Export/Import use
+the same format:
+
+```
+G1=key:ctrl+c,ctrl+v
+G2=command:/usr/bin/firefox
+G3=disabled:
+```
+
+`<type>:<target>`, one line per key. `key` is a captured sequence (lowercase
+`gdk_keyval_name` output; modifiers joined with `+`, steps joined with `,`),
+`command` is a program/file path, `disabled` is inactive.
+
+## Assets
+`find_asset()` resolves in order: `$GKEYMAPPER_ASSETS_DIR` → `./assets` →
+compiled-in `ASSETS_DIR` (`/usr/local/share/gkeymapper/assets`). The icon
+(`assets/icon.png`) is used in the header bar and the About dialog.
+
+## Driving the GUI for manual checks
+There is no `xdotool`/`wtype` on this machine, and the capture-dialog buttons
+(`Clear`/`Cancel`/`Done`) expose an empty AT-SPI accessible name — the text is in
+a child `label` node, so target the button by its child label. `pyatspi`
+(`queryAction().doAction(0)`) plus `Xlib`'s `xtest.fake_input` can click buttons
+and inject keys. Warn the user before synthesizing keystrokes or stealing window
+focus.