lcp 0.1.0

data/docs/reference/i18n.md

@@ -0,0 +1,497 @@
+# Internationalization (i18n) Reference
+
+LCP Ruby uses Rails standard `I18n` for all translatable strings. The engine ships with English defaults in `config/locales/en.yml`. Host applications override or extend these by placing locale files in `config/locales/`.
+
+## Key Hierarchy
+
+All engine keys live under the `lcp_ruby` namespace. Host-app model/presenter keys follow the patterns below.
+
+### Model Names
+
+Used in page headings, breadcrumbs, flash messages, and the "New" button.
+
+```yaml
+lcp_ruby:
+  models:
+    employee:
+      one: "Employee"         # singular (show heading, flash)
+      other: "Employees"      # plural (index heading, breadcrumb)
+```
+
+### Field Labels
+
+Used in table column headers, form labels, show page labels, and advanced filter field names.
+
+```yaml
+lcp_ruby:
+  models:
+    employee:
+      fields:
+        first_name: "First Name"
+        employment_start_date: "Employment Start Date"
+```
+
+**Dot-path fields** (e.g., `employee.full_name` on a `hire_detail` presenter) resolve against the **target model's** field translations, not the presenter's own model.
+
+### Enum Display Labels
+
+Two equivalent paths are supported — define one or both:
+
+```yaml
+# Path 1: under models (recommended)
+lcp_ruby:
+  models:
+    employee:
+      enums:
+        gender:
+          "0": "Male"
+          "1": "Female"
+
+# Path 2: under enums (legacy, also checked)
+lcp_ruby:
+  enums:
+    employee:
+      gender:
+        "0": "Male"
+        "1": "Female"
+```
+
+Resolution order: i18n lookup (path 1, then path 2) > YAML `label` from enum definition > humanized value.
+
+**Important:** Enum values must be quoted strings in YAML, even for numeric values (e.g., `"0"`, not `0`).
+
+### Presenter Section Titles
+
+Used in form and show page section headings (`<h2>`).
+
+```yaml
+lcp_ruby:
+  presenters:
+    employees:
+      sections:
+        identity: "Identity"
+        employment: "Employment"
+        organization: "Organization"
+```
+
+The lookup key is derived by parameterizing the section title from the presenter YAML: `"Basic Info"` becomes `basic_info`. The i18n key is:
+
+```
+lcp_ruby.presenters.<presenter_name>.sections.<parameterized_title>
+```
+
+If the i18n key is not found, the raw YAML title is used as fallback.
+
+### Menu Labels
+
+Menu item labels are resolved via i18n when no explicit `label_key` is provided:
+
+```yaml
+lcp_ruby:
+  menu:
+    hr_turnover: "HR Turnover"
+    codelists: "Codelists"
+    settings: "Settings"
+    log_out: "Log out"
+```
+
+The lookup key is the parameterized label: `"HR Turnover"` becomes `hr_turnover`, `"Log out"` becomes `log_out`. The full key path is `lcp_ruby.menu.<parameterized_label>`.
+
+For explicit control, use `label_key` on the menu item:
+
+```yaml
+# menu.yml
+- label: "Settings"
+  label_key: "lcp_ruby.menu.settings"
+  url: /settings
+```
+
+### Action Labels
+
+Built-in single actions (show, edit, delete) use:
+
+```yaml
+lcp_ruby:
+  actions:
+    show: "Show"
+    edit: "Edit"
+    delete: "Delete"
+    column_header: "Actions"
+```
+
+The collection "create" button uses `action["label"]` from the presenter YAML, or falls back to `lcp_ruby.actions.new_record` with `%{model}` interpolation:
+
+```yaml
+lcp_ruby:
+  actions:
+    new_record: "New %{model}"
+```
+
+Custom action labels:
+
+```yaml
+lcp_ruby:
+  actions:
+    archive_employee: "Archive Employee"
+```
+
+## UI Framework Keys
+
+These keys control general UI elements. All have English defaults in the engine; override them in your locale file.
+
+### Quick lookup — common buttons & labels
+
+Every label rendered by the built-in views uses one of these keys. If you only translate this short list, the index/show/form/edit screens are fully localized.
+
+| UI element | I18n key | English default |
+|---|---|---|
+| "Create" submit button | `lcp_ruby.form.create` | Create |
+| "Update" submit button | `lcp_ruby.form.update` | Update |
+| "Cancel" form button | `lcp_ruby.form.cancel` | Cancel |
+| "More" actions dropdown | `lcp_ruby.form.more_actions` | More |
+| Row "Show" link | `lcp_ruby.actions.show` | Show |
+| Row "Edit" link | `lcp_ruby.actions.edit` | Edit |
+| Row "Delete" link | `lcp_ruby.actions.delete` | Delete |
+| Actions column header | `lcp_ruby.actions.column_header` | Actions |
+| Collection "New X" button | `lcp_ruby.actions.new_record` | New %{model} |
+| Edit-page breadcrumb | `lcp_ruby.breadcrumbs.edit` | Edit |
+| New-page breadcrumb | `lcp_ruby.breadcrumbs.new` | New |
+| Home crumb | `lcp_ruby.breadcrumbs.home` | Home |
+| "Back to list" toolbar | `lcp_ruby.toolbar.back_to_list` | Back to list |
+| "Copy link" toolbar | `lcp_ruby.toolbar.copy_url` | Copy link |
+| Boolean true/false | `lcp_ruby.boolean.true_label` / `.false_label` | Yes / No |
+| Search placeholder | `lcp_ruby.search.placeholder` | Search... |
+
+The subsections below show these keys grouped by namespace (matching the YAML structure you'll write in your locale file).
+
+### Boolean Renderer
+
+```yaml
+lcp_ruby:
+  boolean:
+    true_label: "Yes"
+    false_label: "No"
+```
+
+### Form Buttons
+
+```yaml
+lcp_ruby:
+  form:
+    create: "Create"
+    update: "Update"
+    cancel: "Cancel"
+    more_actions: "More"
+```
+
+### Breadcrumbs
+
+```yaml
+lcp_ruby:
+  breadcrumbs:
+    home: "Home"
+    edit: "Edit"
+    new: "New"
+```
+
+### Search
+
+```yaml
+lcp_ruby:
+  search:
+    placeholder: "Search..."
+    submit: "Search"
+```
+
+### Advanced Filter
+
+```yaml
+lcp_ruby:
+  advanced_filter:
+    toggle: "Filters"
+    add_filter: "+ Add filter"
+    add_or_group: "+ Add OR group"
+    apply: "Apply filters"
+    clear: "Clear all"
+    select_field: "Select field..."
+    select_operator: "Select operator..."
+    enter_value: "Enter value..."
+    enter_values: "Enter values separated by commas"
+    between_separator: "—"
+    last_n_days_suffix: "days"
+    active_filters: "%{count} active"
+    group_label: "OR"
+    combinator_and: "AND"
+    combinator_or: "OR"
+    field_groups:
+      direct: "Fields"
+      custom_fields: "Custom Fields"
+      scopes: "Scopes"
+```
+
+### Search Operators
+
+Used in the advanced filter operator dropdown:
+
+```yaml
+lcp_ruby:
+  search:
+    operators:
+      eq: "equals"
+      not_eq: "not equals"
+      cont: "contains"
+      not_cont: "not contains"
+      start: "starts with"
+      not_start: "does not start with"
+      end: "ends with"
+      not_end: "does not end with"
+      gt: "greater than"
+      gteq: "greater or equal"
+      lt: "less than"
+      lteq: "less or equal"
+      between: "is between"
+      in: "is one of"
+      not_in: "is not one of"
+      present: "is present"
+      blank: "is blank"
+      "null": "is null"
+      not_null: "is not null"
+      "true": "is true"
+      not_true: "is not true"
+      "false": "is false"
+      not_false: "is not false"
+      last_n_days: "in the last N days"
+      this_week: "this week"
+      this_month: "this month"
+      this_quarter: "this quarter"
+      this_year: "this year"
+```
+
+### Pagination
+
+```yaml
+lcp_ruby:
+  pagination:
+    showing_range: "Showing %{first}-%{last} of %{total} records"
+    total_only:
+      one: "1 record"
+      other: "%{count} records"
+  per_page:
+    label: "Show"
+```
+
+### Flash Messages
+
+```yaml
+lcp_ruby:
+  flash:
+    created: "%{model} was successfully created."
+    updated: "%{model} was successfully updated."
+    deleted: "%{model} was successfully deleted."
+```
+
+### Confirmations
+
+```yaml
+lcp_ruby:
+  confirmations:
+    confirm: "Confirm"
+    cancel: "Cancel"
+    confirm_delete: "Delete Record"
+    confirm_delete_message: "Are you sure you want to delete this record? This action cannot be undone."
+```
+
+### Toolbar
+
+```yaml
+lcp_ruby:
+  toolbar:
+    back_to_list: "Back to list"
+    copy_url: "Copy link"
+    copied: "Copied!"
+```
+
+## Date Formatting
+
+The date renderer uses `I18n.l(value, format: :default)`. Define date formats using standard Rails i18n keys (outside the `lcp_ruby` namespace):
+
+```yaml
+cs:
+  date:
+    formats:
+      default: "%d.%m.%Y"
+    day_names: ["neděle", "pondělí", "úterý", "středa", "čtvrtek", "pátek", "sobota"]
+    month_names: [~, "leden", "únor", "březen", "duben", "květen", "červen", "červenec", "srpen", "září", "říjen", "listopad", "prosinec"]
+```
+
+> YAML flow arrays with non-ASCII content must quote each entry. Without quotes Psych raises `did not find expected node content`, which is unhelpful — wrap each name in `"…"`.
+
+Without locale-specific date formats, dates render as ISO 8601 (`2024-03-01`).
+
+> **Czech baseline shipped by the engine.** `config/locales/cs.yml` ships in the gem and provides Czech defaults for `date.*`, `time.*`, `number.*`, and `support.array.*` — so a host app can set `config.i18n.default_locale = :cs` without crashing on the first `I18n.l(Date.today)` call. Host apps may override any key in their own `config/locales/cs.yml`; engine UI translations (`lcp_ruby.*`) still need to come from your locale file or `rails-i18n`.
+
+## Authentication translations
+
+When using `authentication: :built_in` (Devise), there are **two** translation surfaces and they are independent:
+
+1. **Engine auth views** (`/auth/login`, `/auth/register`, `/auth/password/new`, profile edit) — owned by LCP and translated via the `lcp_ruby.auth.*` namespace. The English defaults ship in `config/locales/en.yml` (search for `auth:` — covers `login`, `register`, `profile`, `forgot_password`, `reset_password`, `links`, `mailer`).
+2. **Devise system messages** — flash notices like "Signed in successfully", validation errors on `email`/`password`, lockable/confirmable strings. These live under the `devise.*` namespace owned by Devise itself. The engine does **not** ship Devise translations for any locale.
+
+To localize the auth flow into a non-English locale, do both:
+
+**(1) Translate engine auth strings** — copy the `auth:` block from `config/locales/en.yml` into your `config/locales/<locale>.yml` and translate values:
+
+```yaml
+cs:
+  lcp_ruby:
+    auth:
+      title: "Přihlášení"
+      login:
+        heading: "Přihlásit se"
+        submit: "Přihlásit"
+        remember_me: "Zapamatovat si mě"
+      register:
+        heading: "Vytvořit účet"
+        submit: "Vytvořit účet"
+        password_hint: "minimálně %{count} znaků"
+      forgot_password:
+        heading: "Zapomenuté heslo?"
+        submit: "Odeslat instrukce pro reset"
+      links:
+        login: "Přihlásit se"
+        register: "Vytvořit účet"
+        forgot_password: "Zapomenuté heslo?"
+      # ... copy & translate the remaining keys from en.yml
+```
+
+**(2) Add Devise translations** — the simplest path is the [`devise-i18n`](https://github.com/tigrish/devise-i18n) gem, which ships translations for ~50 locales:
+
+```ruby
+# Gemfile
+gem "devise-i18n"
+```
+
+After `bundle install` Devise's flash messages and ActiveRecord error messages on Devise fields are translated automatically — no further setup. If you prefer to manage Devise strings yourself, copy the `devise:` namespace from the [Devise source](https://github.com/heartcombo/devise/blob/main/config/locales/en.yml) into your locale file.
+
+If you skip step (2), Devise flashes ("Signed in successfully", "Invalid Email or password") will remain in English even when the rest of the UI is fully translated — that is a pure-Devise concern, not an LCP gap.
+
+## Complete Reference
+
+This page documents the most commonly translated keys. The engine defines many more keys for features like batch actions, saved filters, approvals, export/import dialogs, authentication screens, audit history, tree structures, and developer tools.
+
+The authoritative source is [`config/locales/en.yml`](../../config/locales/en.yml) — it contains every translatable key with its English default. Copy the relevant sections to your locale file as a starting point for translation.
+
+## Host-translatable namespaces (cheat sheet)
+
+The 2026-04 i18n sweep added or extended these namespaces. The engine ships English defaults for all of them; override any key in your host locale file.
+
+| Namespace | Purpose |
+|---|---|
+| `lcp_ruby.actions.{not_authorized, execution_failed, enqueued, pipeline_failed}` | Flash/result messages from `Actions::ActionExecutor`, `BatchActions::CustomActionDispatcher`, `ActionsController` |
+| `lcp_ruby.background_jobs.definition_not_found` | `ExecutorJob` error-message column when a job type is unknown |
+| `lcp_ruby.custom_fields.flash.*` | `CustomFieldsController` flash notices (create/update/delete/bulk/delete_failed) |
+| `lcp_ruby.custom_fields.{expand_label, collapse_label, section_title}` | Manage-screen UI labels and default section title for custom fields without an explicit section |
+| `lcp_ruby.auth.not_authorized_action` / `auth.not_authorized_short` | `Controller::Authorization#user_not_authorized` flash + JSON body |
+| `lcp_ruby.auth.errors.prevented_{registration,update}` | Registration/profile-update error headers (one/other forms) |
+| `lcp_ruby.form.errors.{prevented_save, select_at_least, select_at_most}` | Resource form error header + multi-select validation (count-based, one/other forms) |
+| `lcp_ruby.form.id_placeholder` | Non-LCP foreign-key fallback placeholder |
+| `lcp_ruby.workflow.errors.registry_unavailable` | Flash when workflow registry isn't available |
+| `lcp_ruby.workflow.errors.task.*` / `delegation.*` | Approval-task action errors surfaced via `ApprovalTasksController` flashes |
+| `lcp_ruby.export.errors.*` | `Export::ExportHandler` failure paths |
+| `lcp_ruby.export.{date_format_iso8601, date_format_epoch, boolean_*, decimal_*, exporting, button_label}` | Export-dialog format option labels + JS button states |
+| `lcp_ruby.import.errors.*` (extended) | `Import::RowProcessor` + `ImportDialogHandler` row-level and pipeline errors |
+| `lcp_ruby.import.mapper.*` | Import mapper table headers and select options (JS) |
+| `lcp_ruby.import.sheet_too_many_rows` | Sheet-validation feedback (XLSX imports) |
+| `lcp_ruby.saved_filters.{not_available, no_conditions_to_save}` | SavedFilters 404 body + JS validation |
+| `lcp_ruby.advanced_filter.{add_subgroup, associations_separator, group_suffix, select_blank, parameterized_placeholder, ql_network_error}` | Advanced filter UI extensions |
+| `lcp_ruby.sort.reorder_*` | Index-sortable drag-drop error flashes (JS) |
+| `lcp_ruby.zone_tabs.load_error` | Turbo frame load-error fallback (JS) |
+| `lcp_ruby.upload.{in_progress, complete, failed}` | Direct-upload status text (JS) |
+| `lcp_ruby.tree.errors.reparent_failed` | Tree reparent error alert (JS) |
+| `lcp_ruby.inline_create.generic_error` | Inline-create dialog generic error (JS) |
+| `lcp_ruby.file_upload.too_large` | File preview size-limit suffix (JS) |
+| `lcp_ruby.dev_toolbar.{loading_metadata, request_failed, reload_page, no_presenter_data, …}` | Dev toolbar UI labels |
+| `lcp_ruby.breadcrumbs.{unknown, custom_fields}` | Fallback breadcrumb labels |
+| `lcp_ruby.errors.{record_not_found, record_not_found_message}` | 404 response bodies |
+| `lcp_ruby.api.{stale_message_short, unavailable}` | External data-source stale/error messages |
+
+### The `app.title` host-override contract
+
+The browser `<title>` is built in the layout as:
+
+```erb
+<% app_title_default = Rails.application.class.module_parent_name.humanize %>
+<% app_title = I18n.t("lcp_ruby.app.title", default: app_title_default).presence || app_title_default %>
+<title><%= [content_for(:title).presence, app_title].compact.join(" — ") %></title>
+```
+
+The engine does **not** ship `lcp_ruby.app.title` in `config/locales/en.yml` — it is a host-override contract resolved at runtime. A host app named `Acme` automatically gets `<title>Acme</title>` (from `Rails.application.class.module_parent_name.humanize`). Hosts may override `lcp_ruby.app.title` in their own locale files; blank overrides are treated as missing.
+
+Per-view prefix via `content_for :title`:
+
+```erb
+<%# in any view template — sets the prefix the layout joins with " — App Name" %>
+<% content_for :title, t("lcp_ruby.models.employee.other", default: "Employees") %>
+```
+
+With nothing set the title is just `App Name`. With the snippet above it becomes `Employees — App Name`. Hosts who want a different separator override the layout (normal Rails extension point).
+
+## Contributing new strings
+
+When adding a new user-visible string to the engine:
+
+1. **Use `I18n.t("lcp_ruby.<ns>.<key>", default: "<humanized>")`**. The `default:` is mandatory so the engine works without a host locale file and the English wording is visible in PR diffs.
+2. **Interpolate with `%{name}` placeholders**; never concatenate.
+   ```ruby
+   I18n.t("lcp_ruby.background_jobs.definition_not_found",
+          job_type: execution.job_type,
+          default: "Job definition '%{job_type}' not found")
+   ```
+3. **For counted nouns use `count:` with `one`/`other` forms** — never Rails `pluralize(n, "noun")`, which keeps the English noun regardless of locale.
+   ```yaml
+   prevented_save:
+     one: "1 error prevented this record from being saved:"
+     other: "%{count} errors prevented this record from being saved:"
+   ```
+4. **Exception messages, log lines, and machine-readable JSON codes are exempt** — they are developer- or operator-facing. But if an exception's `#message` bubbles into a flash, JSON response body, or rendered HTML, it **is** in scope; use the `LcpRuby::Error#localized_message` pattern (pass an i18n key to the constructor; the catch site calls `e.localized_message`). See the workflow approval flow for the canonical example.
+5. **Translations are plain text by default.** If a key contains HTML, name it with the `_html` suffix — Rails recognizes the suffix and marks the result `html_safe`. Otherwise the renderer must escape the result (flash rendering and JSON auto-escape; `render plain:` never interprets markup).
+
+The regression guard catches reintroduced hardcoded strings:
+
+- **Ruby**: `LcpRuby/NoHardcodedI18nString` cop (AST-precise, flags `redirect_to notice:/alert:`, `flash[_] = "…"`, `render plain:/json:`, `Actions::Result.new(message:)`, `.failure(…)`, `error_message:` keyword, `placeholder:` in form helpers, `pluralize(_, "noun")`). Runs as part of `bin/rubocop`. Allow-list via `# rubocop:disable LcpRuby/NoHardcodedI18nString`.
+- **ERB + JavaScript**: `bundle exec rake lcp_ruby:i18n_lint` (regex patterns for `<title>`, attribute literals, `alert/confirm/prompt`, `textContent`, `new Error(…)` etc.). Allow-list via trailing `<%# i18n-exempt: <reason> %>` (ERB) or `// i18n-exempt: <reason>` (JS) on the same line.
+
+## Automatic locale binding
+
+The engine wraps every request in `I18n.with_locale(...)` via the `LcpRuby::Controller::LocaleBinding` concern (included in both `LcpRuby::ApplicationController` and `LcpRuby::Auth::BaseController`). Resolution order (first non-nil wins):
+
+1. **`current_user.profile[:locale]`** — when a logged-in user has a known locale stored. Writers: the "My Settings" presenter, `PreferencesController`, any `user.update!(profile_data: ...)` call.
+2. **`Accept-Language` header** — a best-effort regex scan over `HTTP_ACCEPT_LANGUAGE`. Picks the first two-letter language prefix that appears in `I18n.available_locales`. Used for anonymous visitors and for logged-in users who haven't set a locale yet.
+3. **`I18n.default_locale`** — standard Rails fallback.
+
+Host apps no longer need a custom `before_action :set_locale` or an initializer that `prepend_before_action`s the controller stack. The only locale-related configuration a host needs in `application.rb` is:
+
+```ruby
+config.i18n.available_locales = %i[en cs de fr]
+config.i18n.default_locale = :en
+```
+
+Unknown user locales, malformed `Accept-Language` headers, and missing `profile_data` all fall through silently to the next step — no exception is surfaced.
+
+## Host app setup
+
+- **Enable Rails i18n fallback to `:en`** in non-test environments so any host locale missing an engine key falls back to the shipped English default:
+  ```ruby
+  # config/application.rb
+  config.i18n.fallbacks = [:en]
+  ```
+  Rails' default fallback chain does not always include `:en`; without this setting, missing host-locale keys can surface as raw key paths instead of the default text.
+- **`<title>` resolves from `lcp_ruby.app.title`** (runtime default: `Rails.application.class.module_parent_name.humanize`). Set it explicitly in your locale file to override:
+  ```yaml
+  en:
+    lcp_ruby:
+      app:
+        title: "Acme HRIS"
+  ```
+- **Devise mailer subjects** live under the standard Devise `devise.mailer.*` namespace, not under `lcp_ruby.*`. Host apps that translate the engine's auth flow must override Devise keys directly. The engine ships only the mailer body templates under `app/views/lcp_ruby/auth/mailer/` (all already i18n'd); Devise itself provides the subjects.
+- **Mailer templates ship as `.html.erb` only.** Engine auth mailers and Devise defaults are `Content-Type: text/html`, not `multipart/alternative`. For deliverability/accessibility install [`premailer-rails`](https://github.com/fphilipe/premailer-rails) (auto-generates `text/plain` from HTML) or add `.text.erb` siblings to override individual templates. This is a MIME concern, not an i18n concern — a platform-level fix is captured under "Mailer hardening" in [`docs/proposals/pending-extensions.md`](../proposals/pending-extensions.md).