Initial Commit

packages/localization/i18n/i18n-shared/src/constants/interpolation-defaults.md

@@ -0,0 +1,77 @@
+# `DEFAULT_INTERPOLATION` — interpolation engine defaults
+
+## Purpose
+
+`DEFAULT_INTERPOLATION` is the canonical default configuration for the
+ICU interpolation engine that ships with `@suaveplan/i18n-icu-parser`
+(Wave 2 of the modular split). Centralising the defaults here lets
+every leaf package — the parser, the catalog, the slim core, even
+custom plugins — agree on the same delimiter pair and nesting limit
+without re-declaring the literals. Consumers that want to override
+the defaults can spread them at construction time
+(`{ ...DEFAULT_INTERPOLATION, prefix: "${" }`); the immutable shape
+ensures no consumer can accidentally mutate the defaults at module
+init.
+
+## Features
+
+- Mustache-compatible delimiters (`{{` / `}}`) — drop-in for catalogs
+  authored against any popular i18n format
+- `maxDepth: 10` ceiling — short-circuits pathological recursion
+- `as const` shape — string literals narrow at the type level for
+  branded types
+- Frozen at module-init via `as const` — no consumer can mutate
+
+## Usage: Basic Example
+
+```ts
+import { DEFAULT_INTERPOLATION } from "@suaveplan/i18n-shared";
+
+const prefix = DEFAULT_INTERPOLATION.prefix;   // "{{"
+const suffix = DEFAULT_INTERPOLATION.suffix;   // "}}"
+const maxDepth = DEFAULT_INTERPOLATION.maxDepth; // 10
+```
+
+## Usage: Advanced Example
+
+```ts
+import { DEFAULT_INTERPOLATION } from "@suaveplan/i18n-shared/constants/interpolation-defaults";
+
+// Override the prefix / suffix while keeping the depth limit
+const customDelimiters = {
+    ...DEFAULT_INTERPOLATION,
+    prefix: "${",
+    suffix: "}",
+} as const;
+
+// Pass the custom shape to the interpolation engine (parser package
+// will accept this shape verbatim)
+const interpolation = customDelimiters; // type-narrowed
+```
+
+## API Reference
+
+### `DEFAULT_INTERPOLATION`
+
+Frozen object literal with these fields:
+
+| Field | Type | Value |
+|---|---|---|
+| `prefix` | `"{{"` | Opening placeholder delimiter |
+| `suffix` | `"}}"` | Closing placeholder delimiter |
+| `maxDepth` | `10` | Maximum nested-resolution depth |
+
+Throws: nothing — read-only constant.
+
+## Implementation Notes
+
+- The choice of `{{` / `}}` matches Mustache, Handlebars, and i18next
+  out of the box. Catalogs authored against any of those tools load
+  without rewriting placeholders.
+- The `maxDepth` of 10 is empirical — pathological self-referencing
+  catalogs (`{"a": "{{a}}"}`) are detected within 10 expansions
+  while well-formed nested-key cases (rare beyond depth 3) still
+  complete normally.
+- The shape is `as const` (NOT a Zod schema) because every consumer
+  of this constant treats it as the authoritative literal — there is
+  no boundary parsing required at this layer.