feat: add defineConfig method (#2086)

packages/cli/package.json

@@ -23,6 +23,10 @@
     "lingui": "./dist/lingui.js"
   },
   "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
     "./api": {
       "types": "./dist/api/index.d.ts",
       "default": "./dist/api/index.js"

packages/cli/src/index.ts

@@ -0,0 +1 @@
+export { defineConfig } from "@lingui/conf"

packages/conf/src/defineConfig.ts

@@ -0,0 +1,8 @@
+import { LinguiConfig } from "./types"
+
+/**
+ * Type helper for lingui.config.ts, returns {@link LinguiConfig} object
+ */
+export function defineConfig(config: LinguiConfig): LinguiConfig {
+  return config
+}

packages/conf/src/index.test.ts

@@ -2,8 +2,18 @@ import path from "path"
 import { getConfig } from "./getConfig"
 import { makeConfig } from "./makeConfig"
 import { mockConsole, getConsoleMockCalls } from "@lingui/jest-mocks"
+import { defineConfig } from "./defineConfig"
+import { LinguiConfig } from "./types"
 
 describe("@lingui/conf", () => {
+  describe("defineConfig", () => {
+    it("Should simply return a passed config", () => {
+      const config: LinguiConfig = { locales: ["en", "pl"], sourceLocale: "en" }
+
+      expect(defineConfig(config)).toStrictEqual(config)
+    })
+  })
+
   it("should return default config", () => {
     mockConsole((console) => {
       const config = getConfig({

packages/conf/src/index.ts

@@ -1,3 +1,4 @@
 export { makeConfig } from "./makeConfig"
+export { defineConfig } from "./defineConfig"
 export { getConfig } from "./getConfig"
 export * from "./types"

website/docs/guides/custom-extractor.md

@@ -20,7 +20,7 @@ We are constantly updating the extractor to keep up with the latest ECMAScript f
 If you are using experimental features (Stage 0 - Stage 2), you'll need to configure a custom list of parser plugins. This can be done by overriding the default extractor and using the `extractFromFileWithBabel()` function:
 
 ```ts title="lingui.config.ts"
-import { extractFromFileWithBabel } from "@lingui/cli/api";
+import { extractFromFileWithBabel, defineConfig } from "@lingui/cli/api";
 import type { ParserPlugin } from "@babel/parser";
 
 export function getBabelParserOptions(filename: string) {
@@ -38,7 +38,7 @@ export function getBabelParserOptions(filename: string) {
   return parserPlugins;
 }
 
-const config: LinguiConfig = {
+export default defineConfig({
   // [...]
   extractors: [
     {
@@ -53,9 +53,7 @@ const config: LinguiConfig = {
       },
     },
   ],
-};
-
-export default config;
+});
 ```
 
 ## Other Frameworks or Custom Syntax
@@ -89,14 +87,12 @@ To use the custom extractor, you need to add it to your Lingui configuration fil
 
 ```ts title="lingui.config.ts" {1,6}
 import { extractor } from "./my-custom-extractor.ts";
-import { LinguiConfig } from "@lingui/conf";
+import { defineConfig } from "@lingui/cli";
 
-const config: LinguiConfig = {
+export default defineConfig({
   // [...]
   extractors: [extractor],
-};
-
-export default config;
+});
 ```
 
 :::caution Important

website/docs/guides/custom-formatter.md

@@ -14,15 +14,17 @@ A formatter is an object with two main functions, `parse` and `serialize`, which
 The formatter can be configured directly in your `lingui.config.{ts,js}` file - no separate package is needed:
 
 ```ts title="lingui.config.{ts,js}"
+import { defineConfig } from "@lingui/cli";
 import { extractor } from "./my-custom-extractor.ts";
-module.exports = {
+
+export default defineConfig({
   // [...]
   format: {
     catalogExtension: "json",
     parse: (content: string): CatalogType => JSON.parse(content),
     serialize: (catalog: CatalogType): string => JSON.stringify(catalog),
   },
-};
+});
 ```
 
 ## Reference

website/docs/guides/pseudolocalization.md

@@ -15,14 +15,16 @@ It also makes it easy to identify hard-coded strings and improperly concatenated
 
 To configure pseudolocalization, add the [`pseudoLocale`](/ref/conf#pseudolocale) property to your Lingui configuration file:
 
-```json title="lingui.config.js"
-{
-  "locales": ["en", "pseudo-LOCALE"],
-  "pseudoLocale": "pseudo-LOCALE",
-  "fallbackLocales": {
-    "pseudo-LOCALE": "en"
-  }
-}
+```ts title="lingui.config.{ts,js}"
+import { defineConfig } from "@lingui/cli";
+
+export default defineConfig({
+  locales: ["en", "pseudo-LOCALE"],
+  pseudoLocale: "pseudo-LOCALE",
+  fallbackLocales: {
+    "pseudo-LOCALE": "en",
+  },
+});
 ```
 
 The `pseudoLocale` option must be set to any string that matches a value in the [`locales`](/ref/conf#locales) configuration. If this is not set correctly, no folder or pseudolocalization will be created.

website/docs/installation.mdx

@@ -87,8 +87,9 @@ Lingui needs a configuration file to work. The configuration file specifies the
 Let's create a basic configuration file in the root of your project (next to `package.json`):
 
 ```js title="lingui.config.js"
-/** @type {import('@lingui/conf').LinguiConfig} */
-module.exports = {
+import { defineConfig } from "@lingui/cli";
+
+export default defineConfig({
   sourceLocale: "en",
   locales: ["cs", "en"],
   catalogs: [
@@ -97,7 +98,7 @@ module.exports = {
       include: ["src"],
     },
   ],
-};
+});
 ```
 
 The configuration above specifies the source locale as English and the target locales as Czech and English.

website/docs/misc/i18next.md

@@ -37,8 +37,9 @@ document.getElementById("output").innerHTML = i18next.t("key");
 The equivalent example with Lingui looks like this:
 
 ```js title="lingui.config.{js,ts}"
-/** @type {import('@lingui/conf').LinguiConfig} */
-module.exports = {
+import { defineConfig } from "@lingui/cli";
+
+export default defineConfig({
   sourceLocale: "en",
   locales: ["en", "cs", "fr"],
   catalogs: [
@@ -47,7 +48,7 @@ module.exports = {
       include: ["src"],
     },
   ],
-};
+});
 ```
 
 ```js

website/docs/ref/catalog-formats.md

@@ -33,12 +33,13 @@ npm install --save-dev @lingui/format-po
 ### Usage {#po-usage}
 
 ```js title="lingui.config.{js,ts}"
+import { defineConfig } from "@lingui/cli";
 import { formatter } from "@lingui/format-po";
 
-export default {
+export default defineConfig({
   // [...]
   format: formatter({ lineNumbers: false }),
-};
+});
 ```
 
 ### Configuration {#po-configuration}
@@ -114,12 +115,13 @@ npm install --save-dev @lingui/format-po-gettext
 ### Usage {#po-gettext-usage}
 
 ```js title="lingui.config.{js,ts}"
+import { defineConfig } from "@lingui/cli";
 import { formatter } from "@lingui/format-po-gettext";
 
-export default {
+export default defineConfig({
   // [...]
   format: formatter({ lineNumbers: false }),
-};
+});
 ```
 
 ### Configuration {#po-gettext-configuration}
@@ -201,12 +203,13 @@ npm install --save-dev @lingui/format-json
 ### Usage {#json-usage}
 
 ```js title="lingui.config.{js,ts}"
+import { defineConfig } from "@lingui/cli";
 import { formatter } from "@lingui/format-json";
 
-export default {
+export default defineConfig({
   // [...]
   format: formatter({ style: "lingui" }),
-};
+});
 ```
 
 ### Configuration {#json-configuration}
@@ -270,12 +273,13 @@ npm install --save-dev @lingui/format-csv
 ### Usage {#csv-usage}
 
 ```js title="lingui.config.{js,ts}"
+import { defineConfig } from "@lingui/cli";
 import { formatter } from "@lingui/format-csv";
 
-export default {
+export default defineConfig({
   // [...]
   format: formatter(),
-};
+});
 ```
 
 This formatter has no configurable options.

website/docs/ref/conf.md

@@ -381,12 +381,13 @@ Default value: `po`
 Message catalog format. The `po` formatter is used by default. Other formatters are available as separate packages.
 
 ```js title="lingui.config.{js,ts}"
-import { formatter } from "@lingui/format-po"
+import { defineConfig } from "@lingui/cli";
+import { formatter } from "@lingui/format-po";
 
-export default {
-  [...]
-  format: formatter({ lineNumbers: false })
-}
+export default defineConfig({
+  // [...]
+  format: formatter({ lineNumbers: false }),
+});
 ```
 
 Read more about available formatters in [Catalog Formats](/ref/catalog-formats) or create your own [Custom Formatter](/guides/custom-formatter).

website/docs/ref/extractor-vue.md

@@ -13,11 +13,11 @@ npm install --save-dev @lingui/extractor-vue
 It is required that you use JavaScript or TypeScript for your Lingui configuration.
 
 ```js title="lingui.config.{js,ts}"
+import { defineConfig } from "@lingui/cli";
 import { vueExtractor } from "@lingui/extractor-vue";
 import babel from "@lingui/cli/api/extractors/babel";
 
-/** @type {import('@lingui/conf').LinguiConfig} */
-const linguiConfig = {
+export default defineConfig({
   locales: ["en", "nb"],
   sourceLocale: "en",
   catalogs: [
@@ -27,9 +27,7 @@ const linguiConfig = {
     },
   ],
   extractors: [babel, vueExtractor],
-};
-
-export default linguiConfig;
+});
 ```
 
 ## See Also