refactor: rename lintDirective to outputPrefix and update related docs and tests

Author: Gamote

packages/cli/src/api/compile.test.ts

@@ -288,15 +288,15 @@ describe("createCompiledCatalog", () => {
     })
   })
 
-  describe("options.lintDirective", () => {
-    const getCompiledCatalog = (lintDirective?: string) =>
+  describe("options.outputPrefix", () => {
+    const getCompiledCatalog = (outputPrefix?: string) =>
       createCompiledCatalog(
         "en",
         {
           Hello: "Hello",
         },
         {
-          lintDirective,
+          outputPrefix,
         }
       ).source
 
@@ -306,19 +306,24 @@ describe("createCompiledCatalog", () => {
     })
 
     it("should use oxlint-disable directive", () => {
-      const result = getCompiledCatalog("oxlint-disable")
+      const result = getCompiledCatalog("/*oxlint-disable*/")
       expect(result).toContain("/*oxlint-disable*/")
     })
 
-    it("should use custom lint directive when specified", () => {
-      const result = getCompiledCatalog("biome-ignore lint: auto-generated")
+    it("should use custom prefix when specified", () => {
+      const result = getCompiledCatalog("/*biome-ignore lint: auto-generated*/")
       expect(result).toContain("/*biome-ignore lint: auto-generated*/")
       expect(result).not.toContain("eslint-disable")
     })
 
-    it("should handle empty string directive", () => {
+    it("should handle empty string prefix (no header)", () => {
       const result = getCompiledCatalog("")
-      expect(result).toContain("/**/")
+      expect(
+        result.startsWith("export") ||
+          result.startsWith("module") ||
+          result.startsWith("window") ||
+          result.startsWith("global")
+      ).toBeTruthy()
     })
   })
 

packages/cli/src/api/compile.ts

@@ -17,7 +17,7 @@ export type CreateCompileCatalogOptions = {
   namespace?: CompiledCatalogNamespace
   pseudoLocale?: string
   compilerBabelOptions?: GeneratorOptions
-  lintDirective?: string
+  outputPrefix?: string
 }
 
 export type MessageCompilationError = {
@@ -45,7 +45,7 @@ export function createCompiledCatalog(
     namespace = "cjs",
     pseudoLocale,
     compilerBabelOptions = {},
-    lintDirective = "eslint-disable",
+    outputPrefix = "/*eslint-disable*/",
   } = options
   const shouldPseudolocalize = locale === pseudoLocale
 
@@ -93,7 +93,7 @@ export function createCompiledCatalog(
     ...compilerBabelOptions,
   }).code
 
-  return { source: `/*${lintDirective}*/` + code, errors }
+  return { source: `${outputPrefix}` + code, errors }
 }
 
 function buildExportStatement(

packages/cli/src/api/compile/compileLocale.ts

@@ -110,7 +110,7 @@ async function compileAndWrite(
     {
       strict: false,
       namespace,
-      lintDirective: options.lintDirective,
+      outputPrefix: options.outputPrefix,
       pseudoLocale: config.pseudoLocale,
       compilerBabelOptions: config.compilerBabelOptions,
     }

packages/cli/src/lingui-compile.ts

@@ -22,7 +22,7 @@ export type CliCompileOptions = {
   watch?: boolean
   namespace?: string
   workersOptions: WorkersOptions
-  lintDirective?: string
+  outputPrefix?: string
 }
 
 export async function command(
@@ -114,7 +114,7 @@ type CliArgs = {
   config?: string
   debounce?: number
   workers?: number
-  lintDirective?: string
+  outputPrefix?: string
 }
 
 if (require.main === module) {
@@ -138,8 +138,8 @@ if (require.main === module) {
       "Debounces compilation for given amount of milliseconds"
     )
     .option(
-      "--lint-directive <directive>",
-      "Add custom lint directive to the compiled files. Useful for enforcing linting rules on generated files. Defaults to 'eslint-disable'"
+      "--output-prefix <prefix>",
+      "Add a custom string to the beginning of compiled files (header/prefix). Useful for tools like linters or coverage directives. Defaults to '/*eslint-disable*/'"
     )
     .on("--help", function () {
       console.log("\n  Examples:\n")
@@ -171,7 +171,7 @@ if (require.main === module) {
         typescript:
           options.typescript || config.compileNamespace === "ts" || false,
         namespace: options.namespace, // we want this to be undefined if user does not specify so default can be used
-        lintDirective: options.lintDirective,
+        outputPrefix: options.outputPrefix,
       })
     )
 

packages/cli/src/test/compile.test.ts

@@ -457,8 +457,8 @@ msgstr "{plural,  }"
     })
   })
 
-  describe("lintDirective", () => {
-    it("Should use custom lint directive in compiled files", async () => {
+  describe("outputPrefix", () => {
+    it("Should use custom output prefix in compiled files", async () => {
       const rootDir = await createFixtures({
         "en.po": `
 msgid "Hello World"
@@ -474,7 +474,7 @@ msgstr "Witaj świecie"
 
       await mockConsole(async () => {
         const result = await command(config, {
-          lintDirective: "biome-ignore lint: auto-generated",
+          outputPrefix: "/*biome-ignore lint: auto-generated*/",
           workersOptions: {
             poolSize: 0,
           },
@@ -494,7 +494,7 @@ msgstr "Witaj świecie"
       })
     })
 
-    it("Should use oxlint-disable directive", async () => {
+    it("Should use oxlint-disable prefix directive", async () => {
       const rootDir = await createFixtures({
         "en.po": `
 msgid "Test"
@@ -510,7 +510,7 @@ msgstr "Test PL"
 
       await mockConsole(async () => {
         const result = await command(config, {
-          lintDirective: "oxlint-disable",
+          outputPrefix: "/*oxlint-disable*/",
           workersOptions: {
             poolSize: 0,
           },

website/docs/ref/cli.md

@@ -172,7 +172,7 @@ lingui compile
     [--namespace <namespace>]
     [--watch [--debounce <delay>]]
     [--workers]
-    [--lint-directive <directive>]
+    [--output-prefix <prefix>]
 ```
 
 Once you have all the catalogs ready and translated, you can use this command to compile all the catalogs into minified JS/TS files. It compiles message catalogs located in the [`path`](/ref/conf#catalogs) directory and generates minified JavaScript files. The resulting file is a string that is parsed into a plain JS object using `JSON.parse`.
@@ -251,28 +251,31 @@ Worker threads can significantly improve performance on large projects. However,
 
 A larger worker pool also increases memory usage. Adjust this value for your project to achieve the best performance.
 
-#### `--lint-directive <directive>` {#compile-lint-directive}
+#### `--output-prefix <prefix>` {#compile-output-prefix}
 
-Customize the lint directive added to the header of compiled message catalogs. By default, Lingui adds `/*eslint-disable*/` to prevent linters from reporting issues in generated files.
+Adds a custom string to the beginning of compiled message catalogs (a header/prefix). By default, Lingui adds `/*eslint-disable*/` to prevent linters from reporting issues in generated files.
 
-This option is useful when using different linters or tools that require specific directive formats.
+Use this option for other tools that rely on header directives (e.g., different linters, coverage tools, or formatters). Provide the full prefix exactly as it should appear in the output.
 
-**Default value:** `eslint-disable`
+**Default value:** `/*eslint-disable*/`
 
 **Examples:**
 
 ```shell
 # For Oxlint
-lingui compile --lint-directive "oxlint-disable"
+lingui compile --output-prefix "/*oxlint-disable*/"
 
 # For Biome
-lingui compile --lint-directive "biome-ignore lint: auto-generated"
+lingui compile --output-prefix "/*biome-ignore lint: auto-generated*/"
+
+# For no prefix at all
+lingui compile --output-prefix ""
 ```
 
 The generated file header will look like:
 
 ```js
-/*<your-directive>*/export const messages = JSON.parse(...);
+/*your-prefix-here*/ export const messages = JSON.parse("{}");
 ```
 
 ## Configuring the Source Locale