docs: add branded types documentation to README and rule docs

Author: swernerx

README.md

@@ -60,8 +60,46 @@ const label = t("save")  // ❌ Not confused with Lingui
 - 📦 Auto-ignores styling variables (`colorClasses`, `STATUS_COLORS`, `buttonStyles`, etc.)
 - 🔧 Auto-ignores styling helper functions (`getStatusColor`, `getButtonClass`, etc.)
 - 🔢 Auto-ignores numeric/symbolic strings without letters (`"1,00€"`, `"12:30"`)
+- 🏷️ Branded types for custom ignore patterns (loggers, analytics, etc.)
 - 🔒 Verifies Lingui macros actually come from `@lingui/*` packages (no false positives from similarly-named functions)
 
+## Branded Types for Custom Ignore Patterns
+
+For cases not covered by automatic detection (like custom loggers or analytics), this plugin exports branded types you can use to mark strings as "no translation needed":
+
+```ts
+import { unlocalized } from "eslint-plugin-lingui-typescript/types"
+
+// Wrap your logger to ignore all string arguments
+function createLogger(prefix = "[App]") {
+  return unlocalized({
+    debug: (...args: unknown[]) => console.debug(prefix, ...args),
+    info: (...args: unknown[]) => console.info(prefix, ...args),
+    warn: (...args: unknown[]) => console.warn(prefix, ...args),
+    error: (...args: unknown[]) => console.error(prefix, ...args),
+  })
+}
+
+const logger = createLogger()
+logger.info("Server started on port", 3000)  // ✅ Automatically ignored
+logger.error("Connection failed:", error)    // ✅ Automatically ignored
+```
+
+### Available Types
+
+| Type | Use Case |
+|------|----------|
+| `UnlocalizedFunction<T>` | Wrap functions/objects to ignore all string arguments |
+| `unlocalized(value)` | Helper function for automatic type inference |
+| `UnlocalizedText` | Generic technical strings |
+| `UnlocalizedLog` | Logger message parameters (string only) |
+| `UnlocalizedStyle` | Style values (colors, fonts, spacing) |
+| `UnlocalizedClassName` | CSS class names |
+| `UnlocalizedEvent` | Analytics/tracking event names |
+| `UnlocalizedKey` | Storage keys, query keys |
+
+See the [no-unlocalized-strings documentation](docs/rules/no-unlocalized-strings.md#branded-types) for detailed examples.
+
 ## Requirements
 
 - Node.js ≥ 24
@@ -141,6 +179,7 @@ This plugin is a TypeScript-focused alternative to the official [eslint-plugin-l
 | **Styling props** (`*ClassName`, etc.) | Manual whitelist | ✅ Auto-detected |
 | **Styling constants** (`*_COLORS`, etc.) | Manual whitelist | ✅ Auto-detected |
 | **Numeric strings** (`"1,00€"`) | Manual whitelist | ✅ Auto-detected |
+| **Custom ignore patterns** | `ignoreFunctions` only | ✅ Branded types (`unlocalized()`) |
 | **Lingui macro verification** | Name-based only | ✅ Verifies package origin |
 | **ESLint version** | 8.x | 9.x (flat config) |
 | **Config format** | Legacy `.eslintrc` | Flat config only |

docs/rules/no-unlocalized-strings.md

@@ -515,13 +515,33 @@ interface ButtonProps {
 
 ### How It Works
 
-These types use TypeScript's branded type pattern:
+These types use TypeScript's branded type pattern with two different markers:
+
+**Parameter-level branding** (`__linguiIgnore`):
 
 ```ts
 type UnlocalizedLog = string & { readonly __linguiIgnore?: "UnlocalizedLog" }
 ```
 
-The `__linguiIgnore` property is a phantom type marker—it never exists at runtime. The rule checks for this property in the contextual type to determine if a string should be ignored.
+The rule checks if the parameter's contextual type has this property.
+
+**Function-level branding** (`__linguiIgnoreArgs`):
+
+```ts
+type UnlocalizedFunction<T> = T & { readonly __linguiIgnoreArgs?: true }
+```
+
+The rule checks if the object/function being called has this property. If so, all string arguments are ignored.
+
+**The `unlocalized()` helper:**
+
+```ts
+function unlocalized<T>(value: T): UnlocalizedFunction<T> {
+  return value as UnlocalizedFunction<T>
+}
+```
+
+This is an identity function—it returns the input unchanged at runtime. But it changes the compile-time type to include the `__linguiIgnoreArgs` brand, enabling automatic type inference without manual annotations.
 
 ## When Not To Use It