@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/concepts/events-and-actions.md

@@ -0,0 +1,271 @@
+# Events and Actions
+
+Blocks can define _events_ which the block can trigger when something happens on the page, like a button being clicked, an input's value being modified or a page being loaded. Some examples are `onClick` on a [`Button`](/Button) or `onMount` on a [`PageHeaderMenu`](/PageHeaderMenu) block.
+
+All blocks implement `onMount` and `onMountAsync` events. These are useful for triggering actions when a block is mounted. For the `onMount` event, the block only mounts when the event action chain is completed, however, for the `onMountAsync` event, the block will mount as soon as possible while the event actions completes execution.
+
+_Actions_ are tasks that can be executed, like calling a request, linking to a new page or changing a value in state. An array of actions can be defined for an event on a block. If that event gets triggered, those actions will execute sequentially.
+
+The chain of actions will stop executing if the action raises a break condition, or if the action throws an unexpected error.
+
+If a break condition was raised, the user will be shown an error message and no further actions will execute. If an unexpected error is thrown, the app will show an error screen and the error will be logged. To handle errors and break conditions, a `catch` action chain can be defined on the event to handle the error, as described below.
+
+Actions which are `async: true` are an exception to the sequential rule of the actions chain. These actions will be executed asynchronously and the next actions in the chain will not wait for them to finish. If any `async: true` action throws an error, the chain will not be stopped and the event will still be completed successfully.
+
+Each action has an `id`, unique to that action chain, and a `type` field which are required.
+
+Actions can have a `params` field for specifying input parameters when executing the action. Operators used in action `params` will be evaluated right before the action is executed. Some events might have data relating to that event, such as what the new value of an input is, or the row that was clicked in a table. The `event` object can be used in the action using the [`_event`](/_event) operator. Some actions also return values which can be passed to succeeding actions in the same action chain using the [`_actions`](/_actions) operator.
+
+Actions can also have a `skip` field. Operators in the `skip` field will be evaluated before an action is executed, and if the evaluated result is `true`, that action is skipped and the next action is executed.
+
+## Action Schema
+
+The schema for a Lowdefy action is:
+
+- `id: string`: __Required__ - An identifier for the action. It must be unique within the action chain it is defined in.
+- `type: string`: __Required__ - The action type to be used. It must be a valid action type.
+- `skip: boolean`: The test that determines whether the action will be skipped or not. This is usually written as operators which evaluates to a `true` or `false`. __Operators are evaluated__.
+- `async: boolean`: This determines whether the action will be evaluated asynchronously. Operators are __not__ evaluated on `async`.
+- `messages: object`:  __Operators are evaluated__.
+  -  `error: boolean | string`: If `boolean`, whether an error message should be displayed if the action throws an error. Error messages are shown by default. If a `string`, the error message to show to the user.
+  -  `loading: boolean | string`: If `boolean`, whether a loading message should be displayed while the action is executing. Loading messages are not shown by default. If a `string`, the loading message to show to the user.
+  -  `success: boolean | string`: If `boolean`, whether a success message should be displayed if the action completes successfully. Success messages are not shown by default. If a `string`, the success message to show to the user.
+- `params: object`: The input passed to the action. __Operators are evaluated__.
+
+###### Events and actions definition example:
+```yaml
+- id: block_with_actions
+  type: Block
+  properties:
+    # ...
+  events:
+    onEvent1:
+      - id: action1
+        type: ActionType1
+        skip:
+          # Operator expression that returns true if action should be skipped.
+        params:
+          # ...
+      - id: action2
+        type: ActionType2
+    onEvent2:
+      - id: action3
+        type: ActionType3
+        params:
+          # ...
+```
+## The actions object
+
+When events are triggered, each completed action writes its response to the actions object under the action id object key. Thus all following actions in a event action list have access to the responses of all preceding actions in the same event list through the [`_actions`](/_actions) operator.
+
+## The event object
+
+When events are triggered, they can provide a data object describing the event (e.g. a description of the clicked item or uploaded file). This data object can be accessed using the [`_event`](/_event) operator in an action definition.
+
+The schema for passing actions to Lowdefy events is:
+```
+  (eventName: (action | control)[])
+  (eventName: {
+    shortcut?: string | string[],
+    debounce?: {
+      ms?: number,
+      immediate?: boolean,
+    },
+    try: (action | control)[],
+    catch?: (action | control)[],
+  })
+```
+
+## Catching action errors
+
+If one action in the chain of event actions fails by throwing an error, the actions in the list following the failed action will not be executed. To handle any errors thrown by an action, Lowdefy event actions can be provided as lists of `try` and `catch` actions.
+
+###### Event try catch actions example for dealing with action errors:
+```yaml
+- id: block_with_actions
+  type: Block
+  properties:
+    # ...
+  events:
+    onEvent1:
+      try:
+        - id: action1
+          type: ActionType1
+          params:
+            # ...
+        - id: action2
+          type: ActionType2
+      catch:
+        - id: unsuccessful
+          type: ActionType1
+          params:
+            # ...
+```
+
+## Control flow in action lists
+
+An item in an action list is either an action (`id` and `type`) or a control. Action lists support the routine controls [`:if`](/:if), [`:switch`](/:switch) and [`:return`](/:return):
+
+- [`:if`](/:if): Evaluates a condition and executes the `:then` action list if the result is truthy, else the optional `:else` action list.
+- [`:switch`](/:switch): Evaluates `:case` conditions in order and executes the `:then` action list of the first truthy case — later cases are never evaluated. If no case matches, the optional `:default` action list is executed.
+- [`:return`](/:return): Ends the whole event successfully. No further actions execute — not even in enclosing lists — and the event's `catch` actions do not run. A `:return` inside a `catch` list ends the remaining catch actions the same way, but the event keeps its error result.
+
+Branch lists are action lists themselves, so controls can nest, and controls can be used in both `try` and `catch` action lists.
+
+###### Control flow example:
+```yaml
+events:
+  onClick:
+    - id: validate
+      type: Validate
+    - :if:
+        _not:
+          _state: skip_reopen
+      :then:
+        - id: reopen_ticket
+          type: Request
+          params: reopen_ticket
+        - id: redirect
+          type: Link
+          params:
+            pageId: ticket-view
+      :else:
+        - id: show_blocked
+          type: DisplayMessage
+          params:
+            content: Ticket cannot be reopened.
+            status: warning
+```
+
+Actions inside branches are ordinary actions — `skip`, `messages`, `async` and error behavior are unchanged. Actions the event does not execute for a control-flow reason — actions in an untaken branch, in an unmatched case, or after a `:return` — are recorded as skipped, so [`_actions`](/_actions) lookups like `_actions: my_action.skipped` keep working.
+
+### When to use which
+
+- `skip` gates a single action.
+- `:if` gates a group of consecutive actions with one condition.
+- `:switch` replaces a chain of nested `:if`s over mutually exclusive alternatives.
+- `:return` ends the event early — replacing the workaround of throwing an error in a `try` list.
+
+Deep control nesting in an event is a sign the logic belongs in an [API routine](/lowdefy-api).
+
+### Routine controls in events
+
+The control grammar is shared with [API routines](/lowdefy-api): where a control exists on both sides, the syntax and semantics match.
+
+| Routine control | In events | Client answer |
+| --- | --- | --- |
+| `:if` | Yes | Same syntax and semantics as in routines. |
+| `:switch` | Yes | First truthy `:case` wins; later cases are never evaluated; `:default` optional. |
+| `:return` | Yes | Ends the event successfully — replaces the early-`Throw` workaround. |
+| `:for`, `:parallel_for` | No | Loops belong in routines; move the iteration into an API endpoint. |
+| `:parallel` | No | Parallelism belongs in routines; for fire-and-forget on the client, actions already take `async: true`. |
+| `:try` / `:catch` / `:finally` | No | Events already scope errors with `try` / `catch` action lists. |
+| `:set_state` | Already an action | [`SetState`](/SetState). Step-like controls exist server-side only because routines have no actions. |
+| `:throw` | Already an action | [`Throw`](/Throw). |
+| `:reject` | No client meaning | It maps a routine to a 4xx response; on the client, `Throw` covers aborts. |
+| `:log` | No | Server logging concern; no client counterpart planned. |
+
+## Debouncing events
+
+Event debouncing can be turned on by setting the `debounce` field on event objects. If `debounce.immediate` is `true`, leading edge debouncing or throttling will apply, else it will be debounced as trailing edge.
+
+To control the debounce delay, set `debounce.ms` to the number of milliseconds to delay. The default delay is 300 milliseconds. If an event is triggered within that time, the event will not be triggered again. See [debounce vs throttling](https://redd.one/blog/debounce-vs-throttle) for a more detailed explanation.
+
+###### Event trailing edge debouncing example:
+```yaml
+- id: block_with_actions
+  type: Block
+  properties:
+    # ...
+  events:
+    onEvent1:
+      debounce:
+        ms: 1000
+      try:
+        - id: action1
+          type: ActionType1
+          params:
+            # ...
+        - id: action2
+          type: ActionType2
+```
+
+###### Event throttling or leading edge debouncing example:
+```yaml
+- id: block_with_actions
+  type: Block
+  properties:
+    # ...
+  events:
+    onEvent1:
+      debounce:
+        ms: 1000
+        immediate: true
+      try:
+        - id: action1
+          type: ActionType1
+          params:
+            # ...
+        - id: action2
+          type: ActionType2
+```
+
+## Keyboard Shortcuts
+
+Events can be triggered by keyboard shortcuts. Add a `shortcut` property to an event to bind a key combination — when pressed, the event fires as if the user clicked the block. See the [Keyboard Shortcuts](/keyboard-shortcuts) page for the full shortcut format, common shortcuts, recipes, and more.
+
+```yaml
+events:
+  onClick:
+    shortcut: mod+K
+    try:
+      - id: open_search
+        type: SetState
+        params:
+          searchOpen: true
+```
+
+## Page initialization events
+
+The first blocks on a page, usually a [`container`](/container) type block, can define `onInit` and `onInitAsync` events. All blocks have `onMount` and `onMountAsync` events, that can be used to initialize the page or blocks.
+
+The `onInit` event is triggered the first time a page is loaded. This event blocks page render, in other words, the page __will__ remain in a loading state, rendering only the progress bar, until all the actions have completed execution. It can be used to set up [`state`](/page-and-app-state). Actions that take a long time to execute, like `Request`, should be used sparingly here for a better user experience.
+
+The `onInitAsync` event is triggered the first time a page loaded, but does not block page render. In other words, the page __will not__ remain in a loading state until all the actions have completed execution. This is a good place to execute non-blocking tasks or requests that might take longer to execute.
+
+The `onMount` event is triggered every time a block is rendered on a page. This event can be used on any block, and causes the block and it's children to render in their loading state. It typically executes actions that should be run each time a block is loaded, like checking if an id is present in the [url query parameters](/_url_query), or fetching data for [`Selector`](/Selector) options using a [`Request`](/Request) action.
+
+The `onMountAsync` event is triggered every time a block is mounted, but does not render the block in loading.
+
+## Action types
+
+The following actions can be used:
+
+- [`CallMethod`](/CallMethod) - Call a method defined by another block.
+- [`Link`](/Link) - Link to another page.
+- [`Message`](/Message) - Show a message to the user.
+- [`Notification`](/Notification) - Show a notification to the user.
+- [`Request`](/Request) - Call a request.
+- [`Reset`](/Reset) - Reset the page validation and `state`.
+- [`ScrollTo`](/ScrollTo) - Scroll to a point on the page.
+- [`SetGlobal`](/SetGlobal) - Set a value to the `global` variable object.
+- [`SetState`](/SetState) - Set a value to the page `state`.
+- [`Validate`](/Validate) - Validate the inputs on the page.
+
+See additional action type available under the Actions tab in the menu.
+
+## TLDR
+- Events are triggered when something happens on a page, like clicking a button or loading a page.
+- A list of actions are executed sequentially by a triggered event.
+- If an action errors, the actions that follow are skipped.
+- Actions that are `async: true` will not be executed sequentially nor stop the event if they error.
+- Action errors can be handled by providing a list of `try` and `catch` actions to the event.
+- Operators used in action `params` are evaluated right before the action is executed.
+- The [`_actions`](/_actions) operator is available for sequential actions to use the values returned from preceding actions in the chain.
+- Actions have a `skip` field that can be used to skip action execution.
+- Action lists also support the [`:if`](/:if), [`:switch`](/:switch) and [`:return`](/:return) controls — `skip` gates one action, `:if` gates a group, `:switch` picks between alternatives, and `:return` ends the event early.
+- Events support `shortcut` to bind keyboard shortcuts to the event. The shortcut fires the event when the key combination is pressed.
+- The `onInit` event is triggered the first time a page is mounted and keeps the page in loading until all actions have finished.
+- The `onInitAsync` event is triggered the first time a page is mounted and does not keep the page in loading.
+- The `onMount` events is triggered the every time a block is mounted and keeps the block in loading until all actions have finished.
+- The `onMountAsync` event is triggered the every time a block is mounted, after `onMount` has completed, and does not keep the block in loading.

package/content/concepts/hosting-files.md

@@ -0,0 +1,18 @@
+# Hosting Files
+
+A Lowdefy app provides a convenient method to host __public__ files under the `/*` app route. Add content to be hosted publicly by creating a folder named `public` in the root of a Lowdefy project folder, next to the `lowdefy.yaml` file. Place the public content in this folder to host this content with your app.
+
+All content in this folder will be publicly accessible at `{{ APP_URL }}/{{ FILE_PATH_NAME }}`. For example, the logo at the top of this page is hosted at [`https://docs.lowdefy.com/logo-light-theme.png`](http://docs.lowdefy.com/logo-light-theme.png). Sub-folders inside the public folder are supported.
+
+By default, the `public` folder of a Lowdefy app will serve some files which most apps need:
+- `apple-touch-icon.png`: A 180x180px png image file to be used as the apple PWA icon.
+- `icon-32.png`: A 32x32px png image file to be used as fallback favicon for some browsers.
+- `icon-512.png`: A 512x512px png image icon.
+- `icon.svg`: A svg image file which will be used as favicon if supported by browser.
+- `logo-dark-theme.png`: A ~250x72px png image used as the header logo for [`PageHeaderMenu`](/PageHeaderMenu) and [`PageSiderMenu`](/PageSiderMenu) blocks on desktop in dark mode.
+- `logo-light-theme.png`: A ~250x72px png image used as the header logo for `PageHeaderMenu` and `PageSiderMenu` blocks on desktop in light mode.
+- `logo-square-dark-theme.png`: A ~125x125px png image used as the header logo for `PageHeaderMenu` and `PageSiderMenu` blocks on mobile in dark mode.
+- `logo-square-light-theme.png`: A ~125x125px png image used as the header logo for `PageHeaderMenu` and `PageSiderMenu` blocks on mobile in light mode.
+- `manifest.webmanifest`: The app [web manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest).
+
+Any of these files can be overwritten by replacing the file with a modified version. For example, to replace the logo inside the header of `PageSiderMenu` on all pages, add a ~250x72px logo inside the project folder at `/logo-light-theme.png`.

package/content/concepts/i18n.md

@@ -0,0 +1,320 @@
+# Internationalization
+
+Lowdefy ships first-class internationalization (i18n) for end-user apps. One config block at `config.i18n` wires up:
+
+- **Antd component strings** — date pickers, pagination, modal buttons, table empty states, form validation messages — via Ant Design's [`ConfigProvider locale`](https://ant.design/docs/react/i18n).
+- **dayjs date formatting** — `dayjs.locale()` is set automatically for the active locale.
+- **App-author translations** — your own strings via the [`_t`](/_t) operator with [ICU MessageFormat](https://formatjs.io/docs/core-concepts/icu-syntax/) (interpolation, plural rules, gender, select).
+- **Built-in framework strings** — engine and client defaults (e.g. `Loading`, `Success`, `This field is required`) that authors can override per-locale.
+- **Server-rendered translations** — the API resolves `Accept-Language` so server-side requests honor the user's locale.
+
+## Configure
+
+Declare your supported locales and message catalogs under `config.i18n`:
+
+```yaml
+# lowdefy.yaml
+config:
+  i18n:
+    defaultLocale: en-US
+    locales:
+      - { code: en-US, label: English, antd: en_US, dayjs: en }
+      - { code: de-DE, label: Deutsch, antd: de_DE, dayjs: de }
+    messages:
+      en-US:
+        _ref: i18n/en-US.json
+      de-DE:
+        _ref: i18n/de-DE.json
+```
+
+**Per-locale fields:**
+- `code` (required) — BCP 47 locale code (`en-US`, `de-DE`, `zh-CN`, ...).
+- `label` — Human-readable name shown in language pickers.
+- `antd` — Antd locale module name (e.g. `en_US`, `zh_CN`). Loaded dynamically from `antd/locale/{name}`.
+- `dayjs` — Dayjs locale id (e.g. `en`, `zh-cn`).
+
+**Top-level fields:**
+- `defaultLocale` (required) — Locale used when no user preference and no browser match. Must appear in `locales`.
+- `messages` — Translation catalogs keyed by locale code. Use inline maps or `_ref` to JSON files.
+
+Only the locales you declare are bundled — antd and dayjs locale imports are codegen'd at build time, so you don't pay for locales you don't ship.
+
+**Fallback is always `en-US`.** When a key isn't in the active locale, the lookup chain checks `en-US` next, then framework builtins, then the key string. Plugin and module authors should always ship `en-US` translations as a baseline so consumers in any locale see real English copy instead of raw keys when translations are incomplete.
+
+## Translate strings with `_t`
+
+Use the [`_t`](/_t) operator anywhere in your config that accepts a string:
+
+```yaml
+- id: greeting
+  type: Title
+  properties:
+    content:
+      _t: greeting
+```
+
+With ICU MessageFormat values:
+
+```yaml
+- id: cart
+  type: Paragraph
+  properties:
+    content:
+      _t:
+        key: cart.items
+        values:
+          count:
+            _state: itemCount
+```
+
+Where `messages.en-US.cart.items: '{count, plural, one {# item} other {# items}}'`.
+
+**Resolution order** (per `_t` call): active-locale message → `en-US` message → built-in framework message → key as last resort.
+
+## Switch language at runtime
+
+Use the [`SetLocale`](/SetLocale) action and the [`_locale`](/_locale) operator to build a language picker:
+
+```yaml
+- id: lang_picker
+  type: Selector
+  properties:
+    options:
+      _array.map:
+        on:
+          _locale: supported
+        callback:
+          _function:
+            value:
+              __args: 0.code
+            label:
+              __args: 0.label
+    value:
+      _locale: active
+  events:
+    onChange:
+      - id: switch
+        type: SetLocale
+        params:
+          locale:
+            _state: lang_picker
+```
+
+`_locale: supported` returns `[{ code, label, antd, dayjs }, ...]`. Selector options must be an array of `{ value, label }` pairs, so the snippet above projects each locale onto that shape with `_array.map` + `_function`.
+
+User preference persists to `localStorage`. Clear it (and fall back to browser/default) by passing `locale: auto`.
+
+**Resolution at startup:**
+
+1. User preference in `localStorage` (`lowdefy_locale`)
+2. Browser `navigator.languages` best-fit against `config.i18n.locales`
+3. `config.i18n.defaultLocale`
+
+## Built-in language picker on page-shell blocks
+
+The page-shell blocks ([`PageHeaderMenu`](/PageHeaderMenu), [`PageSidebarLayout`](/PageSidebarLayout), [`PageSiderMenu`](/PageSiderMenu)) expose a built-in `localeSelector` property — same shape as the existing `darkModeToggle`. Set it to `true` and a globe-icon dropdown appears in the page chrome alongside the dark-mode toggle. The dropdown lists the locales declared in `config.i18n.locales` and dispatches [`SetLocale`](/SetLocale) on selection. It renders nothing if `config.i18n` is not configured, so flipping the flag in apps that haven't set up i18n is a no-op.
+
+```yaml
+- id: shell
+  type: PageHeaderMenu
+  properties:
+    darkModeToggle: true
+    localeSelector: true
+    menu:
+      links:
+        - label: Home
+          pageId: home
+```
+
+## Built-in framework strings
+
+The framework emits a few user-visible strings (action loading toasts, validation summaries, popup-blocker warnings, the global error page). They live in a built-in catalog and surface as English by default. Override any of them by adding the same key under `config.i18n.messages.{locale}`:
+
+```yaml
+config:
+  i18n:
+    defaultLocale: de-DE
+    locales:
+      - { code: de-DE, label: Deutsch, antd: de_DE, dayjs: de }
+    messages:
+      de-DE:
+        engine.action.loading: 'Laden'
+        engine.action.success: 'Erfolgreich'
+        engine.validation.fieldRequired: 'Pflichtfeld'
+        engine.validation.summary: '{count, plural, one {Eingabe hat # Validierungsfehler} other {Eingabe hat # Validierungsfehler}}'
+        client.popupBlocked: 'Ein Popup-Blocker verhindert das Öffnen der Seite.'
+        client.requestError: 'Anforderungsfehler'
+        errorPage.name: 'Fehler'
+        errorPage.message: 'Ein Fehler ist aufgetreten.'
+        errorPage.homeLink: 'Zurück zur Startseite'
+```
+
+**Built-in keys you can override:**
+
+| Key | English default | Where it surfaces |
+|---|---|---|
+| `engine.action.loading` | `Loading` | Default loading toast on actions |
+| `engine.action.success` | `Success` | Default success toast on actions |
+| `engine.validation.fieldRequired` | `This field is required` | Required-field validation message |
+| `engine.validation.summary` | `Your input has {count} validation error(s)` | `Validate` action error summary (ICU plural) |
+| `client.popupBlocked` | `A popup blocker may be preventing...` | Toast when `Link` to a new tab is blocked |
+| `client.requestError` | `Request error` | Fallback when an API response has no message |
+| `client.backAriaLabel` | `back` | Aria label on browser-back links |
+| `client.shortcutThen` | `then` | Sequence shortcut badge separator |
+| `errorPage.name` | `Error` | Full-page error fallback heading |
+| `errorPage.message` | `An error has occurred.` | Full-page error fallback body |
+| `errorPage.homeLink` | `Return to home page` | Full-page error fallback link |
+
+## Localizing block defaults
+
+Antd's `ConfigProvider locale` automatically translates date-picker placeholders, modal `Ok`/`Cancel` buttons, table empty states, pagination labels, and form validation messages — no per-block work required. When a block exposes a Lowdefy-specific string (e.g. `ControlledList.noDataTitle`, `Search.placeholder`), thread `_t` through the property:
+
+```yaml
+- id: items
+  type: ControlledList
+  properties:
+    noDataTitle:
+      _t: list.empty
+```
+
+## Server-side translations
+
+Server-side actions and requests resolve the user's locale from the `Accept-Language` header. `_t` works the same in server contexts as on the client, with one difference: there's no `localStorage` on the server, so `Accept-Language` (and `defaultLocale`) determine the active locale per request.
+
+## Agents and AI chat UI
+
+**The AgentChat block** (`@lowdefy/blocks-antd-x`) auto-localizes its framework-rendered strings via `methods.translate(key)` against the active locale. Builtin keys:
+
+| Key | Default | Where |
+|---|---|---|
+| `agent.sender.placeholder` | `Type a message...` | Sender input placeholder |
+| `agent.toolApproval.approve` / `.reject` | `Approve` / `Reject` | Tool-approval buttons |
+| `agent.message.copy` / `.feedback` / `.regenerate` / `.delete` | English defaults | Message action menu |
+| `agent.toolResult.completed` / `.completedNoData` | `Completed` / `Completed (no data)` | Tool result captions |
+| `agent.toolResult.empty` / `.emptyList` | `Empty` / `Empty list` | Empty tool-result placeholders |
+| `agent.toolResult.showMore` / `.showLess` | `Show more` / `Show less` | Collapsible long text |
+
+Override per-locale via `config.i18n.messages.{locale}` — same mechanism as any other message.
+
+**antd X built-in strings.** XProvider is wired at the app root with a merged antd + antd-X locale pack. antd X (`@ant-design/x@2.7.x`) ships only two upstream packs: `en_US` and `zh_CN`. Locales outside that set fall back to `en_US` for X-native strings (`New chat`, `Stop loading`, `Like`/`Dislike`, `OK`/`Cancel` on bubble edit). To override these in unsupported locales, set the framework's reference keys under `config.i18n.messages.{locale}`:
+
+```yaml
+config:
+  i18n:
+    defaultLocale: de-DE
+    locales:
+      - { code: de-DE, label: Deutsch, antd: de_DE, dayjs: de }
+    messages:
+      de-DE:
+        agent.antdx.conversations.create: 'Neuer Chat'
+        agent.antdx.sender.stopLoading: 'Anhalten'
+        agent.antdx.bubble.editableOk: 'OK'
+        agent.antdx.bubble.editableCancel: 'Abbrechen'
+        agent.antdx.actions.feedbackLike: 'Gefällt mir'
+        agent.antdx.actions.feedbackDislike: 'Gefällt mir nicht'
+```
+
+**Agent runtime errors.** HTTP 400/500 errors from the agent endpoint (`Only POST requests are supported.`, `Invalid agent path`, `Agent "X" does not exist.`, etc.) translate via `agent.runtime.*` keys against the request's `Accept-Language`. Server-side validation errors and stack traces stay in English (developer diagnostics).
+
+**Agent config translation.** `agent.properties.instructions` passes through the operator parser at request time, so `_t:` works:
+
+```yaml
+agents:
+  - id: assistant
+    type: AISDKAgent
+    connectionId: anthropic
+    properties:
+      agent:
+        model: claude-sonnet-4
+        instructions:
+          _t: agent.systemPrompt
+```
+
+For `tools[].description` — describes when the model should call a tool — keep it static English in most cases. Translating tool descriptions can degrade tool-call accuracy on English-trained models.
+
+**Hook payloads.** Agent hook endpoints (`onStart`, `onStepFinish`, `onFinish`, etc.) receive a payload that now includes `locale: <activeCode>`, so hook routines can return locale-aware follow-up messages.
+
+**Built-in tool descriptions, console warnings, build errors, and the model's natural-language output stay English.** They're either model-facing (translation degrades model behavior), developer-facing (English is standard), or owned by the model.
+
+## From plugin code
+
+`_t` is the YAML-config interface. The runtime equivalent for custom block and action plugins is `methods.translate(key, values)` — same lookup chain, same overrides. Plugin authors should never reach into `lowdefy._internal.t` directly; that's an engine-internal adapter. Use `methods.translate`:
+
+```js
+// in @my-org/blocks-cool/src/blocks/CoolList/CoolList.js
+function CoolList({ blockId, methods, properties }) {
+  const empty = methods.translate('blocks-cool.list.empty');
+  const greeting = methods.translate('blocks-cool.greeting', { name: properties.name });
+  // ...
+}
+```
+
+```js
+// in @my-org/actions-cool/src/actions/CoolAction.js
+function CoolAction({ methods, params }) {
+  const ok = methods.translate('actions-cool.confirm.ok');
+  // ...
+}
+```
+
+## Shipping default messages from a plugin package
+
+Plugins can ship locale-keyed defaults so consumers see translated strings out-of-the-box. Add a `messages` JS module and register it under the package's `exports`:
+
+```js
+// in @my-org/blocks-cool/src/messages.js
+export default {
+  'en-US': {
+    'blocks-cool.list.empty': 'No items',
+    'blocks-cool.list.loading': 'Loading data...',
+  },
+  'de-DE': {
+    'blocks-cool.list.empty': 'Keine Einträge',
+    'blocks-cool.list.loading': 'Daten werden geladen...',
+  },
+};
+```
+
+```json
+// in @my-org/blocks-cool/package.json
+{
+  "exports": {
+    "./types": "./dist/types.js",
+    "./messages": "./dist/messages.js"
+  }
+}
+```
+
+Namespace your keys with the package or org slug (`blocks-cool.*`) to avoid collisions with other plugins. Apps consume your defaults automatically — the build merges plugin manifests into the per-locale message catalog. App authors override individual keys via `config.i18n.messages.{locale}` like any other message.
+
+**Merge precedence:**
+
+| Tier | Source | Wins over |
+|---|---|---|
+| User app messages | `config.i18n.messages.{locale}` in `lowdefy.yaml` | everything below |
+| Plugin messages | plugin's `./messages` export, locale-keyed | builtin |
+| Framework builtins | the built-in catalog (English) | key |
+| Key fallback | the lookup key itself | — |
+
+## Working with dates and numbers
+
+**Date and number input blocks auto-localize their defaults when `config.i18n` is configured:**
+
+- `DateSelector`, `DateRangeSelector`, `DateTimeSelector`, `MonthSelector` — the input/display `format` defaults to the active locale's date format (e.g. `DD.MM.YYYY` for `de-DE`, `MM/DD/YYYY` for `en-US`). Formats are derived at runtime via `Intl.DateTimeFormat` — no per-locale table to maintain.
+- `NumberInput` — `decimalSeparator` defaults to the active locale's separator (e.g. `,` for `de-DE`, `.` for `en-US`), derived via `Intl.NumberFormat`.
+
+Override per-block by setting `properties.format` or `properties.decimalSeparator` explicitly. When `config.i18n` isn't configured the legacy defaults (`YYYY-MM-DD`, `.`) apply so apps without i18n are unchanged.
+
+Two complementary operators also format values per locale in YAML expressions:
+
+- [`_intl`](/_intl) — wraps native `Intl.DateTimeFormat`/`Intl.NumberFormat`/etc. Pass an explicit `locale`, or omit it to use the user's default.
+- [`_dayjs`](/_dayjs) and [`_date`](/_date) — dayjs-based date formatting. `dayjs.locale()` is set automatically by `useLocale`, so locale-aware tokens (`dddd`, `MMMM`, etc.) render in the active language.
+
+**In custom block / action code**, read the active locale with `methods.getLocale()` and pair it with the `@lowdefy/helpers` utilities `getLocaleDateFormat`, `getLocaleDecimalSeparator`, `getLocaleGroupSeparator` to derive locale-aware defaults.
+
+## Reference
+
+- [`_t`](/_t) — translate operator
+- [`_locale`](/_locale) — read active/default/fallback/supported locale state
+- [`SetLocale`](/SetLocale) — set the user's preferred locale
+- [`_intl`](/_intl) — Intl-based date/number/list formatting