docs(formats): add docs for extracted formatters

packages/conf/src/types.ts

@@ -186,9 +186,6 @@ export type LinguiConfig = {
      */
     flow?: boolean
   }
-  /**
-   * @see type GeneratorOptions from "@babel/core"
-   */
   compilerBabelOptions?: any
   fallbackLocales?: FallbackLocales | false
   extractors?: (string | ExtractorType)[]

packages/format-csv/README.md

@@ -0,0 +1,34 @@
+[![License][badge-license]][license]
+[![Version][badge-version]][package]
+[![Downloads][badge-downloads]][package]
+
+# @lingui/format-csv
+
+> Read and write message catalogs in CSV 
+
+`@lingui/format-csv` is part of [LinguiJS][linguijs]. See the
+[documentation][documentation] for all information, tutorials and examples.
+
+## Installation
+
+```sh
+npm install --save-dev @lingui/format-csv
+# yarn add --dev @lingui/format-csv
+```
+
+## Usage
+
+See the [reference][reference] documentation.
+
+## License
+
+This package is licensed under [MIT][license] license.
+
+[license]: https://github.com/lingui/js-lingui/blob/main/LICENSE
+[linguijs]: https://github.com/lingui/js-lingui
+[documentation]: https://lingui.dev
+[reference]: https://lingui.dev/ref/loader
+[package]: https://www.npmjs.com/package/@lingui/format-csv
+[badge-downloads]: https://img.shields.io/npm/dw/@lingui/format-csv.svg
+[badge-version]: https://img.shields.io/npm/v/@lingui/format-csv.svg
+[badge-license]: https://img.shields.io/npm/l/@lingui/format-csv.svg

packages/format-json/README.md

@@ -0,0 +1,94 @@
+[![License][badge-license]][license]
+[![Version][badge-version]][package]
+[![Downloads][badge-downloads]][package]
+
+# @lingui/format-json
+
+> Read and write message catalogs in JSON 
+
+`@lingui/format-json` is part of [LinguiJS][linguijs]. See the
+[documentation][documentation] for all information, tutorials and examples.
+
+## Installation
+
+```sh
+npm install --save-dev @lingui/format-json
+# yarn add --dev @lingui/format-json
+```
+
+## Usage
+
+```js
+// lingui.config.{js,ts}
+import {formatter} from "@lingui/format-json"
+
+export default {
+  [...]
+  format: formatter({style: "lingui"}),
+}
+```
+
+Possible options: 
+
+```ts
+export type JsonFormatterOptions = {
+  /**
+   * Print places where message is used
+   *
+   * @default true
+   */
+  origins?: boolean
+
+  /**
+   * Print line numbers in origins
+   *
+   * @default true
+   */
+  lineNumbers?: boolean
+  /**
+   * Different styles how information could be printed.
+   *
+   * @default "lingui"
+   */
+  style?: "lingui" | "minimal"
+}
+```
+
+
+### Style: minimal
+
+Simple JSON with message ID -> translation mapping. All metadata (default message, comments for translators, message origin, etc) are stripped:
+
+```json
+{
+"MessageID": "Translated Message"
+}
+```
+
+### Style: lingui
+
+Raw catalog data serialized to JSON:
+
+```json
+{
+"MessageID": {
+  "translation": "Translated Message",
+  "message": "Default string (from source code)",
+  "origin": [
+    ["path/to/src.js", 42]
+  ]
+}
+}
+```
+
+## License
+
+This package is licensed under [MIT][license] license.
+
+[license]: https://github.com/lingui/js-lingui/blob/main/LICENSE
+[linguijs]: https://github.com/lingui/js-lingui
+[documentation]: https://lingui.dev
+[package]: https://www.npmjs.com/package/@lingui/format-json
+[badge-downloads]: https://img.shields.io/npm/dw/@lingui/format-json.svg
+[badge-version]: https://img.shields.io/npm/v/@lingui/format-json.svg
+[badge-license]: https://img.shields.io/npm/l/@lingui/format-json.svg

packages/format-json/src/json.ts

@@ -8,8 +8,24 @@ import {
 } from "@lingui/conf"
 
 export type JsonFormatterOptions = {
+  /**
+   * Print places where message is used
+   *
+   * @default true
+   */
   origins?: boolean
+
+  /**
+   * Print line numbers in origins
+   *
+   * @default true
+   */
   lineNumbers?: boolean
+  /**
+   * Different styles how information could be printed.
+   *
+   * @default "lingui"
+   */
   style?: "lingui" | "minimal"
 }
 

packages/format-po-gettext/README.md

@@ -0,0 +1,78 @@
+[![License][badge-license]][license]
+[![Version][badge-version]][package]
+[![Downloads][badge-downloads]][package]
+
+# @lingui/format-po-gettext
+
+> Read and write message catalogs in Gettext PO format with gettext-style plurals
+
+`@lingui/format-po-gettext` is part of [LinguiJS][linguijs]. See the
+[documentation][documentation] for all information, tutorials and examples.
+
+## Catalog example
+
+```po
+#. js-lingui-id: WGI12K
+#. js-lingui:icu=%7BanotherCount%2C+plural%2C+one+%7BSingular+case%7D+other+%7BCase+number+%7BanotherCount%7D%7D%7D&pluralize_on=anotherCount
+msgid "Singular case"
+msgid_plural "Case number {anotherCount}"
+msgstr[0] "Singular case"
+msgstr[1] "Case number {anotherCount}"
+```
+
+## Installation
+
+```sh
+npm install --save-dev @lingui/format-po-gettext
+# yarn add --dev @lingui/format-po-gettext
+```
+
+## Usage
+
+```js
+// lingui.config.{js,ts}
+import {formatter} from "@lingui/format-po-gettext"
+
+export default {
+  [...]
+  format: formatter({lineNumbers: false}),
+}
+```
+
+Possible options:
+
+```ts
+export type PoGettextFormatterOptions = {
+  /**
+   * Print places where message is used
+   *
+   * @default true
+   */
+  origins?: boolean
+
+  /**
+   * Print line numbers in origins
+   *
+   * @default true
+   */
+  lineNumbers?: boolean
+
+  disableSelectWarning?: boolean
+}
+```
+
+## Usage
+
+See the [reference][reference] documentation.
+
+## License
+
+This package is licensed under [MIT][license] license.
+
+[license]: https://github.com/lingui/js-lingui/blob/main/LICENSE
+[linguijs]: https://github.com/lingui/js-lingui
+[documentation]: https://lingui.dev
+[package]: https://www.npmjs.com/package/@lingui/format-po-gettext
+[badge-downloads]: https://img.shields.io/npm/dw/@lingui/format-po-gettext.svg
+[badge-version]: https://img.shields.io/npm/v/@lingui/format-po-gettext.svg
+[badge-license]: https://img.shields.io/npm/l/@lingui/format-po-gettext.svg

packages/format-po/README.md

@@ -0,0 +1,70 @@
+[![License][badge-license]][license]
+[![Version][badge-version]][package]
+[![Downloads][badge-downloads]][package]
+
+# @lingui/format-po
+
+> Read and write message catalogs in Gettext PO format with ICU plurals
+
+`@lingui/format-po` is part of [LinguiJS][linguijs]. See the
+[documentation][documentation] for all information, tutorials and examples.
+
+## Catalog example
+
+```po
+#, Comment for translators
+#: src/App.js:4, src/Component.js:2
+msgid "MessageID"
+msgstr "Translated Message"
+```
+
+## Installation
+
+```sh
+npm install --save-dev @lingui/format-po
+# yarn add --dev @lingui/format-po
+```
+
+## Usage
+
+```js
+// lingui.config.{js,ts}
+import {formatter} from "@lingui/format-po"
+
+export default {
+  [...]
+  format: formatter({lineNumbers: false}),
+}
+```
+
+Possible options:
+
+```ts
+export type PoFormatterOptions = {
+  /**
+   * Print places where message is used
+   *
+   * @default true
+   */
+  origins?: boolean
+
+  /**
+   * Print line numbers in origins
+   *
+   * @default true
+   */
+  lineNumbers?: boolean
+}
+```
+
+## License
+
+This package is licensed under [MIT][license] license.
+
+[license]: https://github.com/lingui/js-lingui/blob/main/LICENSE
+[linguijs]: https://github.com/lingui/js-lingui
+[documentation]: https://lingui.dev
+[package]: https://www.npmjs.com/package/@lingui/format-po
+[badge-downloads]: https://img.shields.io/npm/dw/@lingui/format-po.svg
+[badge-version]: https://img.shields.io/npm/v/@lingui/format-po.svg
+[badge-license]: https://img.shields.io/npm/l/@lingui/format-po.svg

packages/format-po/src/po.ts

@@ -15,7 +15,18 @@ const joinOrigin = (origin: [file: string, line?: number]): string =>
   origin.join(":")
 
 export type PoFormatterOptions = {
+  /**
+   * Print places where message is used
+   *
+   * @default true
+   */
   origins?: boolean
+
+  /**
+   * Print line numbers in origins
+   *
+   * @default true
+   */
   lineNumbers?: boolean
 }
 

website/docs/guides/custom-formatter.md

@@ -0,0 +1,63 @@
+# Custom Formatter
+
+If your project requires some special format or handling logic you can write your own format implementation.
+
+Formatter is simple object with 2 main functions `parse` and `serialize` which should take LinguiJS catalog and serialize it into string and vice-versa.
+
+You don't need to create a separate package for formatter, you can write it directly in `lingui.config.{ts,js}`
+
+```ts title="lingui.config.{ts,js}"
+import { extractor } from './my-custom-extractor.ts'
+module.exports = {
+  [...]
+  format: {
+    catalogExtension: "json",
+    parse: (content: string): CatalogType => JSON.parse(content),
+    serialize: (catalog: CatalogType): string => JSON.stringify(catalog),
+  }
+}
+```
+
+The shape for formatter is following:
+
+```ts
+export type CatalogFormatter = {
+  catalogExtension: string
+  /**
+   * Set extension used when extract to template
+   * Omit if the extension is the same as catalogExtension
+   */
+  templateExtension?: string
+  parse(
+    content: string,
+    ctx: { locale: string | null; filename: string }
+  ): Promise<CatalogType> | CatalogType
+  serialize(
+    catalog: CatalogType,
+    ctx: { locale: string | null; filename: string; existing: string | null }
+  ): Promise<string> | string
+}
+```
+
+Lingui Catalog is an object with following structure:
+
+```ts
+export type CatalogType = {
+  [msgId: string]: MessageType
+}
+
+export type MessageType = {
+  message?: string
+  origin?: MessageOrigin[]
+  comments?: string[]
+  extractedComments?: string[]
+  obsolete?: boolean
+  flags?: string[]
+  context?: string
+  translation?: string
+}
+```
+
+:::caution Important
+If you use TypeScript to create your formatter, you should use the `ts` extension for your Lingui configuration file.
+:::