feat(cli): add --output-prefix option to customize compiled file headers (#2377)

Author: Gamote

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

@@ -288,6 +288,45 @@ describe("createCompiledCatalog", () => {
     })
   })
 
+  describe("options.outputPrefix", () => {
+    const getCompiledCatalog = (outputPrefix?: string) =>
+      createCompiledCatalog(
+        "en",
+        {
+          Hello: "Hello",
+        },
+        {
+          outputPrefix,
+        }
+      ).source
+
+    it("should use default eslint-disable directive when not specified", () => {
+      const result = getCompiledCatalog()
+      expect(result).toContain("/*eslint-disable*/")
+    })
+
+    it("should use oxlint-disable directive", () => {
+      const result = getCompiledCatalog("/*oxlint-disable*/")
+      expect(result).toContain("/*oxlint-disable*/")
+    })
+
+    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 prefix (no header)", () => {
+      const result = getCompiledCatalog("")
+      expect(
+        result.startsWith("export") ||
+          result.startsWith("module") ||
+          result.startsWith("window") ||
+          result.startsWith("global")
+      ).toBeTruthy()
+    })
+  })
+
   it("should return list of compile errors", () => {
     const res = createCompiledCatalog(
       "ru",

packages/cli/src/api/compile.ts

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

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

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

packages/cli/src/lingui-compile.ts

@@ -22,6 +22,7 @@ export type CliCompileOptions = {
   watch?: boolean
   namespace?: string
   workersOptions: WorkersOptions
+  outputPrefix?: string
 }
 
 export async function command(
@@ -113,6 +114,7 @@ type CliArgs = {
   config?: string
   debounce?: number
   workers?: number
+  outputPrefix?: string
 }
 
 if (require.main === module) {
@@ -135,6 +137,10 @@ if (require.main === module) {
       "--debounce <delay>",
       "Debounces compilation for given amount of milliseconds"
     )
+    .option(
+      "--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")
       console.log(
@@ -165,6 +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
+        outputPrefix: options.outputPrefix,
       })
     )
 

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

@@ -456,4 +456,72 @@ msgstr "{plural,  }"
       })
     })
   })
+
+  describe("outputPrefix", () => {
+    it("Should use custom output prefix in compiled files", async () => {
+      const rootDir = await createFixtures({
+        "en.po": `
+msgid "Hello World"
+msgstr "Hello World"
+        `,
+        "pl.po": `
+msgid "Hello World"
+msgstr "Witaj świecie"
+        `,
+      })
+
+      const config = getTestConfig(rootDir)
+
+      await mockConsole(async () => {
+        const result = await command(config, {
+          outputPrefix: "/*biome-ignore lint: auto-generated*/",
+          workersOptions: {
+            poolSize: 0,
+          },
+        })
+
+        const actualFiles = readFsToListing(rootDir)
+
+        expect(actualFiles["en.js"]).toContain(
+          "/*biome-ignore lint: auto-generated*/"
+        )
+        expect(actualFiles["pl.js"]).toContain(
+          "/*biome-ignore lint: auto-generated*/"
+        )
+        expect(actualFiles["en.js"]).not.toContain("eslint-disable")
+        expect(actualFiles["pl.js"]).not.toContain("eslint-disable")
+        expect(result).toBeTruthy()
+      })
+    })
+
+    it("Should use oxlint-disable prefix directive", async () => {
+      const rootDir = await createFixtures({
+        "en.po": `
+msgid "Test"
+msgstr "Test"
+        `,
+        "pl.po": `
+msgid "Test"
+msgstr "Test PL"
+        `,
+      })
+
+      const config = getTestConfig(rootDir)
+
+      await mockConsole(async () => {
+        const result = await command(config, {
+          outputPrefix: "/*oxlint-disable*/",
+          workersOptions: {
+            poolSize: 0,
+          },
+        })
+
+        const actualFiles = readFsToListing(rootDir)
+
+        expect(actualFiles["en.js"]).toContain("/*oxlint-disable*/")
+        expect(actualFiles["en.js"]).not.toContain("eslint-disable")
+        expect(result).toBeTruthy()
+      })
+    })
+  })
 })

website/docs/ref/cli.md

@@ -172,6 +172,7 @@ lingui compile
     [--namespace <namespace>]
     [--watch [--debounce <delay>]]
     [--workers]
+    [--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`.
@@ -250,6 +251,33 @@ 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.
 
+#### `--output-prefix <prefix>` {#compile-output-prefix}
+
+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.
+
+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*/`
+
+**Examples:**
+
+```shell
+# For Oxlint
+lingui compile --output-prefix "/*oxlint-disable*/"
+
+# For Biome
+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-prefix-here*/ export const messages = JSON.parse("{}");
+```
+
 ## Configuring the Source Locale
 
 One limitation of checking for missing translations is that the English message catalog typically does not require translations since our source code is in English. This issue can be resolved by configuring the [`sourceLocale`](/ref/conf#sourcelocale) in the configuration file.