docs: align rule documentation with actual implementation

- consistent-plural-format: document style option (hash/template)
- no-complex-expressions: remove non-existent options
- no-unlocalized-strings: fix default ignoreFunctions values
- text-restrictions: document rules array format
- valid-t-call-location: document class properties as allowed
- README: add migration guide from eslint-plugin-lingui

Author: swernerx

README.md

@@ -91,14 +91,75 @@ Or configure rules manually:
 
 | Rule | Description | Recommended |
 |------|-------------|:-----------:|
-| [no-unlocalized-strings](docs/rules/no-unlocalized-strings.md) | Detects user-visible strings not wrapped in Lingui macros. Uses TypeScript types to automatically ignore technical strings like string literal unions, DOM APIs, Intl methods, and discriminated union fields. | ✅ |
-| [no-single-variable-message](docs/rules/no-single-variable-message.md) | Disallows messages that consist only of a single variable without surrounding text. Such messages provide no context for translators. | ✅ |
-| [no-single-tag-message](docs/rules/no-single-tag-message.md) | Disallows `<Trans>` components that contain only a single JSX element without text. The wrapped element should be translated directly instead. | ✅ |
+| [no-unlocalized-strings](docs/rules/no-unlocalized-strings.md) | Detects user-visible strings not wrapped in Lingui macros. Uses TypeScript types to automatically ignore technical strings like string literal unions, DOM APIs, and Intl methods. | ✅ |
+| [no-single-variable-message](docs/rules/no-single-variable-message.md) | Disallows messages that consist only of variables without surrounding text. Such messages provide no context for translators. | ✅ |
+| [no-single-tag-message](docs/rules/no-single-tag-message.md) | Disallows `<Trans>` components that contain only a single JSX element without text. The wrapped element should have surrounding text for context. | ✅ |
 | [no-nested-macros](docs/rules/no-nested-macros.md) | Prevents nesting Lingui macros inside each other (e.g., `t` inside `<Trans>`). Nested macros create invalid message catalogs and confuse translators. | ✅ |
-| [no-complex-expressions-in-message](docs/rules/no-complex-expressions-in-message.md) | Restricts embedded expressions in messages to simple identifiers and member access. Complex expressions like function calls or ternaries should be extracted to variables. | ✅ |
-| [valid-t-call-location](docs/rules/valid-t-call-location.md) | Ensures `t` macro calls are inside functions, not at module scope. Module-level calls execute before i18n is initialized and won't update on locale change. | ✅ |
-| [consistent-plural-format](docs/rules/consistent-plural-format.md) | Validates `<Plural>` component usage by ensuring required plural keys (`one`, `other`) are present. Helps maintain consistent pluralization across the codebase. | ✅ |
-| [text-restrictions](docs/rules/text-restrictions.md) | Enforces project-specific text restrictions like disallowed patterns or minimum length. Requires configuration to be useful. | — |
+| [no-complex-expressions-in-message](docs/rules/no-complex-expressions-in-message.md) | Restricts embedded expressions to simple identifiers only. Complex expressions like `${user.name}` or `${formatPrice(x)}` must be extracted to named variables first. | ✅ |
+| [valid-t-call-location](docs/rules/valid-t-call-location.md) | Ensures `t` macro calls are inside functions or class properties, not at module scope. Module-level calls execute before i18n is initialized and won't update on locale change. | ✅ |
+| [consistent-plural-format](docs/rules/consistent-plural-format.md) | Enforces consistent plural value format — either `#` hash syntax or `${var}` template literals throughout the codebase. | ✅ |
+| [text-restrictions](docs/rules/text-restrictions.md) | Enforces project-specific text restrictions with custom patterns and messages. Requires configuration. | — |
+
+## Migrating from eslint-plugin-lingui
+
+This plugin is a TypeScript-focused alternative to the official [eslint-plugin-lingui](https://github.com/lingui/eslint-plugin-lingui). Here are the key differences:
+
+### Key Differences
+
+| Feature | eslint-plugin-lingui | eslint-plugin-lingui-typescript |
+|---------|---------------------|--------------------------------|
+| **Type-aware detection** | ❌ Heuristics only | ✅ Uses TypeScript types |
+| **String literal unions** | Manual whitelist | ✅ Auto-detected |
+| **DOM API strings** | Manual whitelist | ✅ Auto-detected |
+| **Intl method arguments** | Manual whitelist | ✅ Auto-detected |
+| **ESLint version** | 8.x | 9.x (flat config) |
+| **Config format** | Legacy `.eslintrc` | Flat config only |
+
+### Why Switch?
+
+1. **Less configuration**: TypeScript's type system automatically identifies technical strings — no need to maintain long whitelists of ignored functions and patterns.
+
+2. **Fewer false positives**: Strings typed as literal unions (like `"loading" | "error"`) are automatically recognized as non-translatable.
+
+3. **Modern ESLint**: Built for ESLint 9's flat config from the ground up.
+
+### Rule Mapping
+
+| eslint-plugin-lingui | eslint-plugin-lingui-typescript |
+|---------------------|--------------------------------|
+| `lingui/no-unlocalized-strings` | `lingui-ts/no-unlocalized-strings` |
+| `lingui/t-call-in-function` | `lingui-ts/valid-t-call-location` |
+| `lingui/no-single-variables-to-translate` | `lingui-ts/no-single-variable-message` |
+| `lingui/no-expression-in-message` | `lingui-ts/no-complex-expressions-in-message` |
+| `lingui/no-single-tag-to-translate` | `lingui-ts/no-single-tag-message` |
+| `lingui/text-restrictions` | `lingui-ts/text-restrictions` |
+| — | `lingui-ts/no-nested-macros` (new) |
+| — | `lingui-ts/consistent-plural-format` (new) |
+
+### Migration Steps
+
+1. Remove the old plugin:
+   ```bash
+   npm uninstall eslint-plugin-lingui
+   ```
+
+2. Install this plugin:
+   ```bash
+   npm install --save-dev eslint-plugin-lingui-typescript
+   ```
+
+3. Update your ESLint config to flat config format (if not already):
+   ```ts
+   // eslint.config.ts
+   import linguiPlugin from "eslint-plugin-lingui-typescript"
+
+   export default [
+     // ... other configs
+     linguiPlugin.configs["flat/recommended"]
+   ]
+   ```
+
+4. Review your ignore lists — many entries may no longer be needed thanks to type-aware detection.
 
 ## Related Projects
 

docs/rules/consistent-plural-format.md

@@ -1,68 +1,97 @@
 # consistent-plural-format
 
-Ensure `<Plural>` component has required plural category props.
+Enforce consistent plural format style (`#` hash or `${var}` template).
 
 ## Why?
 
-Proper pluralization requires specific props for different quantities. Missing props can cause:
-- Runtime errors or fallback to incorrect text
-- Incomplete translations
-- Poor user experience for different languages
+Lingui supports two formats for interpolating the count value in plural messages:
+
+1. **Hash format**: `"# items"` — uses `#` as a placeholder
+2. **Template format**: `` `${count} items` `` — uses template literals
+
+Mixing both styles in a codebase leads to inconsistency and confusion. This rule enforces one style throughout your project.
 
 ## Rule Details
 
-This rule ensures that `<Plural>` components include all required plural category props.
+This rule checks `plural()` calls and `<Plural>` components and reports when the wrong format style is used.
 
-### ❌ Invalid
+### With `style: "hash"` (default)
+
+#### ❌ Invalid
 
 ```tsx
-// Missing 'other' (required by default)
-<Plural value={count} one="# item" />
+// Template format when hash is required
+plural(count, {
+  one: `${count} item`,
+  other: `${count} items`
+})
+
+<Plural
+  value={count}
+  one={`${count} item`}
+  other={`${count} items`}
+/>
+```
 
-// Missing 'one' (required by default)
-<Plural value={count} other="# items" />
+#### ✅ Valid
 
-// Missing both required props
-<Plural value={count} zero="None" />
+```tsx
+// Hash format
+plural(count, {
+  one: "# item",
+  other: "# items"
+})
+
+<Plural
+  value={count}
+  one="# item"
+  other="# items"
+/>
 ```
 
-### ✅ Valid
+### With `style: "template"`
+
+#### ❌ Invalid
 
 ```tsx
-// All required props present
-<Plural value={count} one="# item" other="# items" />
+// Hash format when template is required
+plural(count, {
+  one: "# item",
+  other: "# items"
+})
+```
 
-// Additional props are allowed
-<Plural value={count} one="One" other="Many" zero="None" />
+#### ✅ Valid
 
-// With expressions
-<Plural value={count} one={oneMsg} other={otherMsg} />
+```tsx
+// Template format
+plural(count, {
+  one: `${count} item`,
+  other: `${count} items`
+})
 ```
 
 ## Options
 
-### `requiredKeys`
+### `style`
 
-Array of plural category props that must be present. Default: `["one", "other"]`
+Which format style to enforce. Default: `"hash"`
 
-Common CLDR plural categories: `zero`, `one`, `two`, `few`, `many`, `other`
+- `"hash"` — Require `#` placeholder (Lingui's standard format)
+- `"template"` — Require `${var}` template literals
 
 ```ts
-// Require only 'other'
+// Enforce hash format (default)
 {
-  "lingui-ts/consistent-plural-format": ["error", {
-    "requiredKeys": ["other"]
-  }]
+  "lingui-ts/consistent-plural-format": ["error", { "style": "hash" }]
 }
 
-// Require zero, one, and other
+// Enforce template format
 {
-  "lingui-ts/consistent-plural-format": ["error", {
-    "requiredKeys": ["zero", "one", "other"]
-  }]
+  "lingui-ts/consistent-plural-format": ["error", { "style": "template" }]
 }
 ```
 
 ## When Not To Use It
 
-If your project uses ICU message format directly in `t` strings instead of `<Plural>` components, this rule won't help. It only checks JSX `<Plural>` components.
+If your project intentionally mixes both formats or you don't use `plural()` / `<Plural>`, you can disable this rule.

docs/rules/no-complex-expressions-in-message.md

@@ -1,109 +1,104 @@
 # no-complex-expressions-in-message
 
-Disallow complex expressions in Lingui messages.
+Disallow complex expressions in Lingui messages — only simple identifiers are allowed.
 
 ## Why?
 
-Complex expressions in translation messages:
-- Make it harder for translators to understand the context
-- Can cause issues with message extraction
-- May lead to runtime errors if the expression fails
-- Make the code harder to maintain
+Complex expressions in translation messages cause problems:
 
-Extract complex logic to variables before using them in messages.
+- **Translators can't understand code**: Expressions like `${user.name}` or `${formatPrice(price)}` are meaningless to translators
+- **Missing context**: Translators need descriptive placeholder names, not code
+- **Extraction issues**: Complex expressions can cause problems with message extraction tools
+- **Maintenance burden**: Inline logic is harder to test and maintain
+
+The solution is simple: extract any complex expression to a named variable first.
 
 ## Rule Details
 
-This rule reports complex expressions inside `t` tagged templates and `<Trans>` components.
+This rule reports any expression inside `t` tagged templates or `<Trans>` components that is not a simple identifier.
+
+**Only simple identifiers are allowed**: `${name}`, `${count}`, `${formattedPrice}`
 
 ### ❌ Invalid
 
 ```tsx
-// Binary/arithmetic expressions
-t`Price: ${price * 1.2}`
-<Trans>Total: {count + 1}</Trans>
+// Member expressions
+t`Hello ${user.name}`
+<Trans>Hello {user.name}</Trans>
 
-// Non-whitelisted function calls
+// Function calls
+t`Price: ${formatPrice(price)}`
 t`Random: ${Math.random()}`
 <Trans>Date: {formatDate(date)}</Trans>
-t`Items: ${items.join(', ')}`
 
-// Member expressions (by default)
-t`Hello ${user.name}`
+// Binary expressions
+t`Total: ${price * 1.2}`
+<Trans>Sum: {a + b}</Trans>
 
 // Conditional expressions
-t`Status: ${isActive ? 'Active' : 'Inactive'}`
+t`Status: ${isActive ? "Active" : "Inactive"}`
 
 // Logical expressions
-t`Name: ${name || 'Unknown'}`
+t`Name: ${name || "Unknown"}`
+
+// Template literals inside expressions
+t`Result: ${`nested ${value}`}`
+
+// Legacy placeholder syntax
+t`Hello ${{ name: userName }}`
 ```
 
 ### ✅ Valid
 
 ```tsx
-// Simple identifiers
+// Simple identifiers only
 t`Hello ${name}`
-<Trans>You have {count} items</Trans>
+t`You have ${count} items`
+<Trans>Hello {name}</Trans>
+<Trans>Total: {formattedTotal}</Trans>
 
-// Whitelisted Lingui helpers
-t`Price: ${i18n.number(price)}`
-t`Date: ${i18n.date(date)}`
-<Trans>Price: {i18n.number(price)}</Trans>
+// Extract complex expressions first
+const displayName = user.name
+t`Hello ${displayName}`
 
-// Extract complex logic first
-const displayPrice = price * 1.2
-t`Price: ${displayPrice}`
+const formattedPrice = formatPrice(price)
+<Trans>Price: {formattedPrice}</Trans>
 
-const formattedDate = formatDate(date)
-<Trans>Date: {formattedDate}</Trans>
-```
+const statusText = isActive ? "Active" : "Inactive"
+t`Status: ${statusText}`
 
-## Options
-
-### `allowedCallees`
+// Whitespace expressions are allowed in JSX
+<Trans>Hello{" "}{name}</Trans>
+```
 
-Array of function names that are allowed. Format: dot-separated strings.
+## Recommended Pattern
 
-Default: `["i18n.number", "i18n.date"]`
+Always extract expressions to descriptively-named variables:
 
-```ts
-{
-  "lingui-ts/no-complex-expressions-in-message": ["error", {
-    "allowedCallees": ["i18n.number", "i18n.date", "formatCurrency"]
-  }]
-}
-```
+```tsx
+// ❌ Bad: translator sees "${user.profile.displayName}"
+t`Welcome back, ${user.profile.displayName}!`
 
-### `allowMemberExpressions`
+// ✅ Good: translator sees "${userName}"
+const userName = user.profile.displayName
+t`Welcome back, ${userName}!`
 
-Whether to allow simple member expressions like `props.name`. Default: `false`
+// ❌ Bad: translator sees "${items.filter(...).length}"
+t`${items.filter(i => i.active).length} active items`
 
-```ts
-{
-  "lingui-ts/no-complex-expressions-in-message": ["error", {
-    "allowMemberExpressions": true
-  }]
-}
+// ✅ Good: translator sees "${activeCount}"
+const activeCount = items.filter(i => i.active).length
+t`${activeCount} active items`
 ```
 
-### `maxExpressionDepth`
+## Options
 
-Maximum depth for member expression chains when `allowMemberExpressions` is `true`. Default: `1`
+This rule has no options. All non-identifier expressions are disallowed.
 
-- `1`: allows `user.name` but not `user.address.street`
-- `2`: allows up to `user.address.street`
-- `null`: no limit
+## Note on Lingui Helpers
 
-```ts
-{
-  "lingui-ts/no-complex-expressions-in-message": ["error", {
-    "allowMemberExpressions": true,
-    "maxExpressionDepth": 2
-  }]
-}
-```
+Unlike some other i18n libraries, Lingui's `plural()`, `select()`, and `selectOrdinal()` should **not** be nested inside `t` templates. Use the JSX components `<Plural>`, `<Select>`, `<SelectOrdinal>` instead, or ICU message syntax in your translation catalog.
 
 ## When Not To Use It
 
-If your codebase has established patterns that rely on inline expressions and you handle translation complexity elsewhere, you can disable this rule.
-
+If your codebase has established patterns that rely heavily on inline expressions and you handle translation complexity elsewhere, you can disable this rule. However, consider the impact on translator experience.