Skip to content

Commit

Permalink
docs: improve catalog format options description (#2050)
Browse files Browse the repository at this point in the history
  • Loading branch information
@andrii-bodnar
andrii-bodnar authored Oct 16, 2024
1 parent 263faa5 commit b8b4b19
Showing 1 changed file with 19 additions and 104 deletions.
123 changes: 19 additions & 104 deletions website/docs/ref/catalog-formats.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,48 +45,13 @@ export default {

PO formatter accepts the following options:

```ts
export type PoFormatterOptions = {
/**
* Print places where message is used
*
* @default true
*/
origins?: boolean;

/**
* Print line numbers in origins
*
* @default true
*/
lineNumbers?: boolean;

/**
* Print `js-lingui-id: Xs4as` statement in extracted comments section
*
* @default false
*/
printLinguiId?: boolean;

/**
* By default, the po-formatter treats the pair `msgid` + `msgctx` as the source
* for generating an ID by hashing its value.
*
* For messages with explicit IDs, the formatter adds a special comment `js-lingui-explicit-id` as a flag.
* When this flag is present, the formatter will use the `msgid` as-is without any additional processing.
*
* @default false
*/
explicitIdAsDefault?: boolean;

/**
* Custom attributes to append to the PO file header
*
* @default {}
*/
customHeaderAttributes?: { [key: string]: string };
};
```
| Option | Type | Default | Description |
| ------------------------ | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `origins` | boolean | `true` | Include comments in the PO file that indicate where each message is used in the source code. This provides additional context during the translation |
| `lineNumbers` | boolean | `true` | Include line numbers in the origin comments. This makes it easier to locate messages in the source code |
| `printLinguiId` | boolean | `false` | Add a `js-lingui-id: hash` comment to each message in the PO file. This ID is a hash generated by Lingui |
| `explicitIdAsDefault` | boolean | `false` | Use the `msgid` as is for messages with explicit IDs. The formatter will add the `js-lingui-explicit-id` flag for such strings |
| `customHeaderAttributes` | `{[key: string]: string}` | `{}` | Allows adding custom key-value pairs to the PO file header |

### Examples {#po-examples}

Expand Down Expand Up @@ -148,37 +113,12 @@ export default {

The PO Gettext formatter accepts the following options:

```ts
export type PoGettextFormatterOptions = {
/**
* Print places where message is used
*
* @default true
*/
origins?: boolean;

/**
* Print line numbers in origins
*
* @default true
*/
lineNumbers?: boolean;

/**
* Disable warning about unsupported `Select` feature encountered in catalogs
*
* @default false
*/
disableSelectWarning?: boolean;

/**
* Overrides the default prefix for icu and plural comments in the final PO catalog.
*
* @default "js-lingui:"
*/
customICUPrefix?: string;
};
```
| Option | Type | Default | Description |
| ---------------------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `origins` | boolean | `true` | Include comments in the PO file that indicate where each message is used in the source code. This provides additional context during the translation |
| `lineNumbers` | boolean | `true` | Include line numbers in the origin comments. This makes it easier to locate messages in the source code |
| `disableSelectWarning` | boolean | `false` | Disable warnings about unsupported `Select` features encountered in catalogs. This can be useful if you're aware of the limitation and want to suppress related warnings |
| `customICUPrefix` | string | `"js-lingui:"` | Override the default prefix for ICU and plural comments in the final PO catalog |

### Examples {#po-gettext-examples}

Expand Down Expand Up @@ -260,37 +200,12 @@ export default {

JSON formatter accepts the following 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 of how information could be printed
*
* @default "lingui"
*/
style?: "lingui" | "minimal";

/**
* Indentation of output JSON
*
* @default 2
*/
indentation?: number;
};
```
| Option | Type | Default | Description |
| ------------- | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `style` | `"lingui"` \| `"minimal"` | `"lingui"` | Specify the output style of the JSON file. `lingui` includes full Lingui-specific metadata, while `minimal` may output a more compact format |
| `origins` | boolean | `true` | Include information in the JSON file about where each message is used in the source code. This provides additional context during the translation |
| `lineNumbers` | boolean | `true` | Include line numbers in the origin comments. This makes it easier to locate messages in the source code |
| `indentation` | number | `2` | Set the number of spaces to use for indentation in the output JSON file. This affects the readability of the file when opened in a text editor |

### Examples {#json-examples}

Expand Down

0 comments on commit b8b4b19

Please sign in to comment.