feat(types): add branded types for marking strings as unlocalized

- UnlocalizedFunction<T> wraps objects to ignore all string arguments
- unlocalized() helper for automatic type inference
- UnlocalizedText, UnlocalizedLog, UnlocalizedStyle, UnlocalizedClassName
- UnlocalizedEvent for analytics, UnlocalizedKey for storage keys
- Detects __linguiIgnore and __linguiIgnoreArgs brands via TypeScript

Author: swernerx

docs/rules/no-unlocalized-strings.md

@@ -358,6 +358,171 @@ const arrows = "→ ← ↑ ↓"
 
 This uses Unicode letter detection (`\p{L}`), so accented characters like `ä`, `ö`, `ü`, `é` are correctly recognized as letters.
 
+## Branded Types
+
+This plugin exports branded types that you can use to mark parameters or properties as "no translation needed". The rule automatically detects these types and ignores strings passed to them.
+
+### Installation
+
+Import the types from the plugin:
+
+```ts
+import type {
+  UnlocalizedFunction,
+  UnlocalizedText,
+  UnlocalizedLog,
+  UnlocalizedStyle,
+  UnlocalizedClassName,
+  UnlocalizedEvent,
+  UnlocalizedKey,
+} from "eslint-plugin-lingui-typescript/types"
+```
+
+### Available Types
+
+| Type | Use Case |
+|------|----------|
+| `UnlocalizedFunction<T>` | Wrap entire function/object to ignore all string arguments |
+| `UnlocalizedText` | Generic catch-all for technical strings |
+| `UnlocalizedLog` | Logger message parameters (string only) |
+| `UnlocalizedStyle` | Style values (colors, fonts, spacing) |
+| `UnlocalizedClassName` | CSS class name strings |
+| `UnlocalizedEvent` | Analytics/tracking event names |
+| `UnlocalizedKey` | Storage keys, query keys, identifiers |
+
+### Example: Custom Logger (Recommended)
+
+Use the `unlocalized()` helper function to wrap logger objects. This is the most flexible approach - all string arguments to any method are automatically ignored, and TypeScript infers the type automatically.
+
+```ts
+import { unlocalized } from "eslint-plugin-lingui-typescript/types"
+
+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),
+  })
+}
+
+// Automatically typed - no manual type annotation needed!
+const logger = createLogger()
+
+// All string arguments are now ignored
+logger.info("Server started on port", 3000)  // ✅ Not flagged
+logger.error("Connection failed:", error)    // ✅ Not flagged
+logger.debug({ request }, "received")        // ✅ Not flagged
+```
+
+Alternatively, you can use `UnlocalizedFunction<T>` directly:
+
+```ts
+import type { UnlocalizedFunction } from "eslint-plugin-lingui-typescript/types"
+
+interface Logger {
+  debug(...args: unknown[]): void
+  info(...args: unknown[]): void
+}
+
+// Option A: Type the variable
+const logger: UnlocalizedFunction<Logger> = createLogger()
+
+// Option B: Type the factory return
+function createLogger(): UnlocalizedFunction<Logger> { ... }
+```
+
+### Example: Custom Logger (String Parameters Only)
+
+If your logger only accepts strings, you can use `UnlocalizedLog` for individual parameters:
+
+```ts
+import type { UnlocalizedLog } from "eslint-plugin-lingui-typescript/types"
+
+interface Logger {
+  debug(message: UnlocalizedLog): void
+  info(message: UnlocalizedLog): void
+  warn(message: UnlocalizedLog): void
+  error(message: UnlocalizedLog): void
+}
+
+const logger: Logger = createLogger()
+logger.info("Starting server on port 3000")  // ✅ Not flagged
+logger.error("Database connection failed")   // ✅ Not flagged
+```
+
+### Example: Analytics/Tracking
+
+```ts
+import type { UnlocalizedEvent } from "eslint-plugin-lingui-typescript/types"
+
+interface Analytics {
+  track(event: UnlocalizedEvent, data?: object): void
+  page(name: UnlocalizedEvent): void
+}
+
+analytics.track("User Signed Up")        // ✅ Not flagged
+analytics.track("Purchase Completed")    // ✅ Not flagged
+```
+
+### Example: Storage Keys
+
+```ts
+import type { UnlocalizedKey } from "eslint-plugin-lingui-typescript/types"
+
+interface Storage {
+  get(key: UnlocalizedKey): string | null
+  set(key: UnlocalizedKey, value: string): void
+}
+
+storage.get("User Preferences")     // ✅ Not flagged
+storage.set("Auth Token", token)    // ✅ Not flagged
+```
+
+### Example: Theme Configuration
+
+```ts
+import type { UnlocalizedStyle } from "eslint-plugin-lingui-typescript/types"
+
+interface ThemeConfig {
+  primaryColor: UnlocalizedStyle
+  fontFamily: UnlocalizedStyle
+  spacing: UnlocalizedStyle
+}
+
+const theme: ThemeConfig = {
+  primaryColor: "#3b82f6",        // ✅ Not flagged
+  fontFamily: "Inter, sans-serif", // ✅ Not flagged
+  spacing: "1rem",                // ✅ Not flagged
+}
+```
+
+### Example: Component Props
+
+```ts
+import type { UnlocalizedClassName } from "eslint-plugin-lingui-typescript/types"
+
+interface ButtonProps {
+  className?: UnlocalizedClassName
+  iconClassName?: UnlocalizedClassName
+  children: React.ReactNode
+}
+
+<Button className="px-4 py-2 bg-blue-500">  // ✅ Not flagged
+  <Trans>Click me</Trans>
+</Button>
+```
+
+### How It Works
+
+These types use TypeScript's branded type pattern:
+
+```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.
+
 ## When Not To Use It
 
 This rule requires TypeScript with type-aware linting enabled. If your project doesn't use TypeScript or doesn't need localization, disable this rule.

package.json

@@ -17,6 +17,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
     }
   },
   "files": [

src/rules/no-unlocalized-strings.test.ts

@@ -391,7 +391,185 @@ ruleTester.run("no-unlocalized-strings", noUnlocalizedStrings, {
 
     // Import/Export paths
     { code: 'import name from "hello"', filename: "test.tsx" },
-    { code: 'export * from "hello_export_all"', filename: "test.tsx" }
+    { code: 'export * from "hello_export_all"', filename: "test.tsx" },
+
+    // =========================================================================
+    // Branded types with __linguiIgnore
+    // =========================================================================
+
+    // UnlocalizedLog branded type
+    {
+      code: `
+        type UnlocalizedLog = string & { readonly __linguiIgnore?: "UnlocalizedLog" }
+        interface Logger {
+          info(message: UnlocalizedLog): void
+        }
+        declare const logger: Logger
+        logger.info("Starting server on port 3000")
+      `,
+      filename: "test.tsx"
+    },
+
+    // UnlocalizedStyle branded type
+    {
+      code: `
+        type UnlocalizedStyle = string & { readonly __linguiIgnore?: "UnlocalizedStyle" }
+        interface ThemeConfig {
+          primaryColor: UnlocalizedStyle
+          fontFamily: UnlocalizedStyle
+        }
+        const theme: ThemeConfig = {
+          primaryColor: "#3b82f6",
+          fontFamily: "Inter, sans-serif"
+        }
+      `,
+      filename: "test.tsx"
+    },
+
+    // UnlocalizedClassName branded type
+    {
+      code: `
+        type UnlocalizedClassName = string & { readonly __linguiIgnore?: "UnlocalizedClassName" }
+        interface ButtonProps {
+          className?: UnlocalizedClassName
+        }
+        function Button(props: ButtonProps) {}
+        <Button className="px-4 py-2 bg-blue-500" />
+      `,
+      filename: "test.tsx"
+    },
+
+    // UnlocalizedText branded type (catch-all)
+    {
+      code: `
+        type UnlocalizedText = string & { readonly __linguiIgnore?: "UnlocalizedText" }
+        interface ApiConfig {
+          endpoint: UnlocalizedText
+        }
+        const config: ApiConfig = {
+          endpoint: "Users endpoint configuration"
+        }
+      `,
+      filename: "test.tsx"
+    },
+
+    // UnlocalizedEvent branded type
+    {
+      code: `
+        type UnlocalizedEvent = string & { readonly __linguiIgnore?: "UnlocalizedEvent" }
+        interface Analytics {
+          track(event: UnlocalizedEvent): void
+        }
+        declare const analytics: Analytics
+        analytics.track("User Signed Up")
+      `,
+      filename: "test.tsx"
+    },
+
+    // UnlocalizedKey branded type
+    {
+      code: `
+        type UnlocalizedKey = string & { readonly __linguiIgnore?: "UnlocalizedKey" }
+        interface Storage {
+          get(key: UnlocalizedKey): string | null
+        }
+        declare const storage: Storage
+        storage.get("User Preferences")
+      `,
+      filename: "test.tsx"
+    },
+
+    // Branded type with function parameter
+    {
+      code: `
+        type UnlocalizedLog = string & { readonly __linguiIgnore?: "UnlocalizedLog" }
+        function log(msg: UnlocalizedLog) {}
+        log("Application started successfully")
+      `,
+      filename: "test.tsx"
+    },
+
+    // Branded type with multiple methods (Logger pattern)
+    {
+      code: `
+        type UnlocalizedLog = string & { readonly __linguiIgnore?: "UnlocalizedLog" }
+        interface Logger {
+          debug(message: UnlocalizedLog, ...args: unknown[]): void
+          info(message: UnlocalizedLog, ...args: unknown[]): void
+          warn(message: UnlocalizedLog, ...args: unknown[]): void
+          error(message: UnlocalizedLog, ...args: unknown[]): void
+        }
+        declare const logger: Logger
+        logger.debug("Debug information here")
+        logger.info("Processing request now")
+        logger.warn("This might be problematic")
+        logger.error("Something went wrong!")
+      `,
+      filename: "test.tsx"
+    },
+
+    // UnlocalizedFunction<T> - wrap entire logger interface
+    {
+      code: `
+        type UnlocalizedFunction<T> = T & { readonly __linguiIgnoreArgs?: true }
+        interface Logger {
+          info(...args: unknown[]): void
+          debug(...args: unknown[]): void
+        }
+        declare const logger: UnlocalizedFunction<Logger>
+        logger.info("Server started on port", 3000)
+        logger.info("Request received")
+        logger.debug({ complex: "object" }, "with message")
+      `,
+      filename: "test.tsx"
+    },
+
+    // UnlocalizedFunction<T> - with factory function return type
+    {
+      code: `
+        type UnlocalizedFunction<T> = T & { readonly __linguiIgnoreArgs?: true }
+        interface Logger {
+          info(...args: unknown[]): void
+          warn(...args: unknown[]): void
+          error(...args: unknown[]): void
+        }
+        declare function createLogger(): UnlocalizedFunction<Logger>
+        const logger = createLogger()
+        logger.info("Application started successfully")
+        logger.warn("This might be a problem")
+        logger.error("Something went wrong!")
+      `,
+      filename: "test.tsx"
+    },
+
+    // UnlocalizedFunction<T> - direct function
+    {
+      code: `
+        type UnlocalizedFunction<T> = T & { readonly __linguiIgnoreArgs?: true }
+        type LogFn = (...args: unknown[]) => void
+        declare const log: UnlocalizedFunction<LogFn>
+        log("Direct function call ignored")
+      `,
+      filename: "test.tsx"
+    },
+
+    // unlocalized() helper function
+    {
+      code: `
+        type UnlocalizedFunction<T> = T & { readonly __linguiIgnoreArgs?: true }
+        function unlocalized<T>(value: T): UnlocalizedFunction<T> { return value }
+        function createLogger() {
+          return unlocalized({
+            info: (...args: unknown[]) => console.info(...args),
+            error: (...args: unknown[]) => console.error(...args),
+          })
+        }
+        const logger = createLogger()
+        logger.info("Server started successfully")
+        logger.error("Connection failed!")
+      `,
+      filename: "test.tsx"
+    }
   ],
   invalid: [
     // Plain string that looks like UI text
@@ -583,6 +761,17 @@ ruleTester.run("no-unlocalized-strings", noUnlocalizedStrings, {
       }`,
       filename: "test.tsx",
       errors: [{ messageId: "unlocalizedString" }]
+    },
+
+    // Branded types without __linguiIgnore should still be flagged
+    {
+      code: `
+        type CustomString = string & { readonly __custom?: "test" }
+        function test(msg: CustomString) {}
+        test("Hello World")
+      `,
+      filename: "test.tsx",
+      errors: [{ messageId: "unlocalizedString" }]
     }
   ]
 })