feat(rules): add valid-t-call-location rule

Enforces that t`...` calls are inside functions, not at module
top-level. Configurable via allowTopLevel option.

Author: swernerx

README.md

@@ -56,10 +56,10 @@ export default [
 | [no-nested-macros](docs/rules/no-nested-macros.md) | Disallow nesting Lingui macros | ✅ |
 | [no-single-tag-message](docs/rules/no-single-tag-message.md) | Disallow messages with only a single markup tag | ✅ |
 | [no-single-variable-message](docs/rules/no-single-variable-message.md) | Disallow messages that consist only of a single variable | ✅ |
+| [valid-t-call-location](docs/rules/valid-t-call-location.md) | Enforce `t` calls inside functions | ✅ |
 
 ### Planned Rules
 
-- `valid-t-call-location` — Enforce valid locations for `t` macro calls
 - `no-unlocalized-strings` — Detect user-visible strings not wrapped in Lingui
 - `text-restrictions` — Enforce project-specific text restrictions
 - `consistent-plural-format` — Ensure consistent plural usage

docs/rules/valid-t-call-location.md

@@ -0,0 +1,90 @@
+# valid-t-call-location
+
+Enforce that `t` macro calls are inside functions, not at module top-level.
+
+## Why?
+
+Using `t` at module top-level causes issues:
+
+- **Evaluation order**: The message is evaluated when the module loads, before the i18n context may be ready
+- **Static extraction**: Some extraction tools expect messages inside functions
+- **Hot reloading**: Top-level values don't update when locale changes
+- **Testing**: Harder to mock or test translations
+
+## Rule Details
+
+This rule reports `t` tagged template expressions that are not inside a function, arrow function, or method.
+
+### ❌ Invalid
+
+```tsx
+// Top-level variable
+const msg = t`Hello`
+
+// Top-level export
+export const greeting = t`Welcome`
+
+// Class property
+class MyClass {
+  message = t`Hello`
+}
+
+// Top-level object
+const config = {
+  message: t`Hello`
+}
+```
+
+### ✅ Valid
+
+```tsx
+// Inside function
+function Component() {
+  const msg = t`Hello`
+  return msg
+}
+
+// Inside arrow function
+const getGreeting = () => t`Welcome`
+
+// Inside method
+class MyClass {
+  getMessage() {
+    return t`Hello`
+  }
+}
+
+// Inside React component
+function App() {
+  return <div>{t`Welcome`}</div>
+}
+
+// Inside callback
+items.map(() => t`Item`)
+
+// Inside hook
+function useTranslation() {
+  return { message: t`Hello` }
+}
+```
+
+## Options
+
+### `allowTopLevel`
+
+When `true`, allows `t` at module top-level. Default: `false`
+
+Use this if you have a build setup that handles top-level translations correctly.
+
+```ts
+{
+  "lingui-ts/valid-t-call-location": ["error", {
+    "allowTopLevel": true
+  }]
+}
+```
+
+## When Not To Use It
+
+If your build setup correctly handles top-level `t` calls (e.g., with compile-time extraction), you can disable this rule or set `allowTopLevel: true`.
+

src/index.ts

@@ -8,6 +8,7 @@ import { noComplexExpressionsInMessage } from "./rules/no-complex-expressions-in
 import { noNestedMacros } from "./rules/no-nested-macros.js"
 import { noSingleTagMessage } from "./rules/no-single-tag-message.js"
 import { noSingleVariableMessage } from "./rules/no-single-variable-message.js"
+import { validTCallLocation } from "./rules/valid-t-call-location.js"
 
 const plugin = {
   meta: {
@@ -18,7 +19,8 @@ const plugin = {
     "no-complex-expressions-in-message": noComplexExpressionsInMessage,
     "no-nested-macros": noNestedMacros,
     "no-single-tag-message": noSingleTagMessage,
-    "no-single-variable-message": noSingleVariableMessage
+    "no-single-variable-message": noSingleVariableMessage,
+    "valid-t-call-location": validTCallLocation
   },
   configs: {} as Record<string, unknown>
 }
@@ -33,7 +35,8 @@ plugin.configs = {
       "lingui-ts/no-complex-expressions-in-message": "error",
       "lingui-ts/no-nested-macros": "error",
       "lingui-ts/no-single-tag-message": "error",
-      "lingui-ts/no-single-variable-message": "error"
+      "lingui-ts/no-single-variable-message": "error",
+      "lingui-ts/valid-t-call-location": "error"
     }
   }
 }

src/rules/valid-t-call-location.test.ts

@@ -0,0 +1,124 @@
+import { RuleTester } from "@typescript-eslint/rule-tester"
+import { afterAll, describe, it } from "vitest"
+
+import { validTCallLocation } from "./valid-t-call-location.js"
+
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parserOptions: {
+      ecmaVersion: 2022,
+      sourceType: "module",
+      ecmaFeatures: {
+        jsx: true
+      }
+    }
+  }
+})
+
+ruleTester.run("valid-t-call-location", validTCallLocation, {
+  valid: [
+    // Inside function declaration
+    `function Component() {
+      const msg = t\`Hello\`
+      return msg
+    }`,
+
+    // Inside arrow function
+    `const Component = () => {
+      const msg = t\`Hello\`
+      return msg
+    }`,
+
+    // Inside function expression
+    `const getMsg = function() {
+      return t\`Hello\`
+    }`,
+
+    // Inside method
+    `class MyClass {
+      getMessage() {
+        return t\`Hello\`
+      }
+    }`,
+
+    // Inside React component
+    `function App() {
+      return <div>{t\`Welcome\`}</div>
+    }`,
+
+    // Inside callback
+    `items.map(() => t\`Item\`)`,
+
+    // Inside event handler
+    `function Component() {
+      const handleClick = () => {
+        alert(t\`Clicked\`)
+      }
+    }`,
+
+    // Inside hook
+    `function useTranslation() {
+      return { message: t\`Hello\` }
+    }`,
+
+    // Non-t tagged templates at top level are fine
+    `const styles = css\`color: red\``,
+    `const html = html\`<div></div>\``,
+
+    // Allow top level when configured
+    {
+      code: `const msg = t\`Hello\``,
+      options: [{ allowTopLevel: true }]
+    }
+  ],
+  invalid: [
+    // Top-level variable declaration
+    {
+      code: `const msg = t\`Hello\``,
+      errors: [{ messageId: "topLevelNotAllowed" }]
+    },
+
+    // Top-level export
+    {
+      code: `export const msg = t\`Welcome\``,
+      errors: [{ messageId: "topLevelNotAllowed" }]
+    },
+
+    // Multiple top-level usages
+    {
+      code: `
+        const greeting = t\`Hello\`
+        const farewell = t\`Goodbye\`
+      `,
+      errors: [
+        { messageId: "topLevelNotAllowed" },
+        { messageId: "topLevelNotAllowed" }
+      ]
+    },
+
+    // Inside class property (not method)
+    {
+      code: `
+        class MyClass {
+          message = t\`Hello\`
+        }
+      `,
+      errors: [{ messageId: "topLevelNotAllowed" }]
+    },
+
+    // Inside object at top level
+    {
+      code: `
+        const config = {
+          message: t\`Hello\`
+        }
+      `,
+      errors: [{ messageId: "topLevelNotAllowed" }]
+    }
+  ]
+})
+

src/rules/valid-t-call-location.ts

@@ -0,0 +1,84 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils"
+
+import { createRule } from "../utils/create-rule.js"
+
+type MessageId = "topLevelNotAllowed"
+
+interface Options {
+  allowTopLevel: boolean
+}
+
+/**
+ * Checks if a node is inside a function, arrow function, or method.
+ */
+function isInsideFunction(node: TSESTree.Node): boolean {
+  let current: TSESTree.Node | undefined = node.parent ?? undefined
+
+  while (current !== undefined) {
+    switch (current.type) {
+      case AST_NODE_TYPES.FunctionDeclaration:
+      case AST_NODE_TYPES.FunctionExpression:
+      case AST_NODE_TYPES.ArrowFunctionExpression:
+      case AST_NODE_TYPES.MethodDefinition:
+        return true
+      default:
+        break
+    }
+    current = current.parent ?? undefined
+  }
+
+  return false
+}
+
+export const validTCallLocation = createRule<[Options], MessageId>({
+  name: "valid-t-call-location",
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Enforce that t macro calls are inside functions, not at module top-level"
+    },
+    messages: {
+      topLevelNotAllowed:
+        "t`...` should not be used at module top-level. Move it inside a function or component."
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          allowTopLevel: {
+            type: "boolean",
+            default: false
+          }
+        },
+        additionalProperties: false
+      }
+    ]
+  },
+  defaultOptions: [
+    {
+      allowTopLevel: false
+    }
+  ],
+  create(context, [options]) {
+    if (options.allowTopLevel) {
+      return {}
+    }
+
+    return {
+      TaggedTemplateExpression(node): void {
+        if (node.tag.type !== AST_NODE_TYPES.Identifier || node.tag.name !== "t") {
+          return
+        }
+
+        if (!isInsideFunction(node)) {
+          context.report({
+            node,
+            messageId: "topLevelNotAllowed"
+          })
+        }
+      }
+    }
+  }
+})
+