From 6b6d1f510576d5edf560ce60ab4cbc9f46eb2b9f Mon Sep 17 00:00:00 2001 From: Vitaly Zakutny Date: Sun, 3 Dec 2023 16:00:13 +0300 Subject: [PATCH] chore: added README for all packages --- README.md | 28 ++++ packages/cli/README.md | 99 +++++++++++++ packages/xml-locales/README.md | 248 +++++++++++++++++++++++++++++++++ 3 files changed, 375 insertions(+) create mode 100644 README.md create mode 100644 packages/cli/README.md create mode 100644 packages/xml-locales/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4dff612 --- /dev/null +++ b/README.md @@ -0,0 +1,28 @@ +# xml-locales + +This repository created to work with localization files in xml and simplified usual jobs like as add, update or remove strings in several XML files. + +## Core package - 📦xml-locales + +This is core package to work with localization files in xml. + +## CLI - 💻@xml-locales/cli + +This is cli tool to work with localization files in xml. + +> [!IMPORTANT] +> This packages, which works with XML files, has one root node named `resources`. This root node has child nodes named `string`. For example: +> +> ```xml +> +> value1 +> value2 +> +>``` + +## Packages + +| Package | version | +| ------- | -------- | +| 📦[xml-locales](https://github.com/Pisyukaev/xml-locales/tree/master/packages/xml-locales) | [![NPM](https://img.shields.io/npm/v/xml-locales.svg)](https://www.npmjs.com/package/xml-locales) | +| 💻[@xml-locales/cli](https://github.com/Pisyukaev/xml-locales/tree/master/packages/cli) | [![NPM](https://img.shields.io/npm/v/@xml-locales/cli.svg)](https://www.npmjs.com/package/@xml-locales/cli) | diff --git a/packages/cli/README.md b/packages/cli/README.md new file mode 100644 index 0000000..a82929d --- /dev/null +++ b/packages/cli/README.md @@ -0,0 +1,99 @@ +# @xml-locales/cli + +[![NPM](https://img.shields.io/npm/v/xml-locales.svg)](https://www.npmjs.com/package/xml-locales) + +This is cli tool to work with localization files in xml. + +## Installation + +```sh +npm install -g @xml-locales/cli +``` + +```sh +yarn global add @xml-locales/cli +``` + +```sh +pnpm add -g @xml-locales/cli +``` + +> [!IMPORTANT] +> This package, which works with XML files, has one root node named `resources`. This root node has child nodes named `string`. For example: +> +> ```xml +> +> value1 +> value2 +> +>``` + +### Or use without + +```sh +npx @xml-locales/cli [...args] +``` + +## Commands + +### Add Command + +The `add` command is used to add a new key-value pair to the XML localization file or files from directory. + +```sh +xml-locales add --path path/to/file_or_directory --key newKey --value newValue +``` + +| Flag | Alias | Default | Description | +|---------|-------|---------|-----------------------------------------------------------------------------| +| `--path`| `-p` | `process.cwd()` | The path to the XML localization file or directory where the key-value pair will be added. | +| `--key` | `-k` | None | The new key to be added. | +| `--value`| `-v` | None | The value to be associated with the new key. | + +### Remove Command + +The `remove` command is used to remove a key-value pair from the XML localization file or files from directory. + +```sh +xml-locales remove --path path/to/file_or_directory --key keyToRemove --value valueToRemove +``` + +| Flag | Alias | Default | Description | +|---------|-------|---------|-----------------------------------------------------------------------------| +| `--path`| `-p` | `process.cwd()` | The path to the XML localization file or directory where the key-value pair will be removed. | +| `--key` | `-k` | None | Removed string by the key. | +| `--value`| `-v` | None | Or removed string by the value. | + +### Update Command + +The `update` command is used to update a key-value pair in the XML localization file or files from directory. + +```sh +xml-locales update --path path/to/file_or_directory --oldValue oldValue --newValue newValue +``` + +| Flag | Alias | Default | Description | +|------------|-------|---------|-----------------------------------------------------------------------------| +| `--path` | `-p` | `process.cwd()` | The path to the XML localization file or directory where the key-value pair will be updated. | +| `--oldValue` | `-o` | None | The old key or value to be updated. | +| `--newValue`| `-n` | None | The new key or value to replace the old one. | + +### Sort Command + +The `sort` command is used to sort the keys in the XML localization file or directory in ascending or descending order. + +```sh +xml-locales sort --path path/to/file_or_directory --direction asc_or_desc +``` + +| Flag | Alias | Default | Description | +|------------|-------|---------|-----------------------------------------------------------------------------| +| `--path` | `-p` | `process.cwd()` | The path to the XML localization file or directory where the keys will be sorted. | +| `--direction` | `-d` | 'asc' | The sort direction. Can be 'asc' for ascending order or 'desc' for descending order. | + +## Packages + +| Package | version | +| ------- | -------- | +| 📦[xml-locales](https://github.com/Pisyukaev/xml-locales/tree/master/packages/xml-locales) | [![NPM](https://img.shields.io/npm/v/xml-locales.svg)](https://www.npmjs.com/package/xml-locales) | +| 💻[@xml-locales/cli](https://github.com/Pisyukaev/xml-locales/tree/master/packages/cli) | [![NPM](https://img.shields.io/npm/v/@xml-locales/cli.svg)](https://www.npmjs.com/package/@xml-locales/cli) | diff --git a/packages/xml-locales/README.md b/packages/xml-locales/README.md new file mode 100644 index 0000000..423bcf4 --- /dev/null +++ b/packages/xml-locales/README.md @@ -0,0 +1,248 @@ +# xml-locales + +[![NPM](https://img.shields.io/npm/v/xml-locales.svg)](https://www.npmjs.com/package/xml-locales) + +This is core package to work with localization files in xml. + +## Installation + +```sh +npm install xml-locales +``` + +```sh +yarn add xml-locales +``` + +```sh +pnpm add xml-locales +``` + +> [!IMPORTANT] +> This package, which works with XML files, has one root node named `resources`. This root node has child nodes named `string`. For example: +> +> ```xml +> +> value1 +> value2 +> +>``` + +## Properties + +| Args | Type | Required | Description | +|------|------|----------|-------------| +| `xmlData` | `string` \| `Buffer` \| `XmlJsonData` | `false` | Data of the xml document | +| `xmlOptions` | `object` | `false` | It represents the options for the XML parser. + +### xmlOptions + +The `xmlOptions` is used to customize the behavior of the XML parser and builder in the `XmlLocales` class. + +| Prop | Type | Required | Description | +|------|------|----------|-------------| +| `parserOptions` | `X2jOptionsOptional` | `false` | Options to customize how the XML data is parsed. See below for details. For more information, see [here](https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/docs/v4/2.XMLparseOptions.md) | +| `builderOptions`| `XmlBuilderOptionsOptional` | `false` | Options to customize how the XML data is built. See below for details. For more information, see [here](https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/docs/v4/3.XMLBuilder.md) | +| `formateOptions`| `XMLFormatterOptions` | `false` | Options to customize the formatting of the XML data. See below for details. For more information, see [here](https://github.com/chrisbottin/xml-formatter#options) | + +### Default Parser Options (X2jOptionsOptional) + +| Option | Value | +|-----------------------|--------| +| `trimValues` | `false` | +| `ignoreDeclaration` | `true` | +| `attributeNamePrefix` | `'key_'` | +| `alwaysCreateTextNode`| `true` | +| `ignoreAttributes` | `false` | + +### Default Builder Options (XmlBuilderOptionsOptional) + +| Option | Value | +|-----------------------|--------| +| `ignoreAttributes` | `false` | +| `attributeNamePrefix` | `'key_'` | +| `processEntities` | `false` | + +### Default Formatter Options (XMLFormatterOptions) + +| Option | Value | +|------------------|--------| +| `collapseContent`| `true` | +| `indentation` | `' '` | + +## Usage + +```js +import {XmlLocales} from 'xml-locales' + +const xmlData = ` + + value1 + value2 + +` + +const xmlLocales = new XmlLocales(xmlData) +const jsonData = xmlLocales.add({key: 'newKey', value: 'newValue'}).toXML() + +console.log(jsonData) +``` + +Output: + +```xml + + value1 + value2 + newValue + +``` + +### Update key/value + +```js +import {XmlLocales} from 'xml-locales' + +const xmlData = ` + + value1 + value2 + +` + +const xmlLocales = new XmlLocales(xmlData) +const jsonData = xmlLocales.add({key: 'newKey', value: 'newValue'}) +.update({oldValue: 'key1', newValue: 'firstKey'}) +.update({oldValue: 'value2', newValue: 'secondValue'}) +.toXML() + +console.log(jsonData) +``` + +Output: + +```xml + + value1 + secondValue + +``` + +### Delete by key/value + +```js +import {XmlLocales} from 'xml-locales' + +const xmlData = ` + + value1 + value2 + +` + +const xmlLocales = new XmlLocales(xmlData) +const jsonData = xmlLocales.add({key: 'newKey', value: 'newValue'}) +.deleteByKey('key1') +.deleteByValue('value2') +.toXML() + +console.log(jsonData) +``` + +Output: + +```xml + + +``` + +### XML and JSON + +```js +import {XmlLocales} from 'xml-locales' + +const xmlData = ` + + value1 + value2 + +` + +const xmlLocales = new XmlLocales(xmlData) +const xmlString = xmlLocales.toXML() +const jsonXml = xmlLocales.toJSON() + +console.log(xmlString) // output XML +console.log(jsonXml) // output JSON +``` + +Output XML: + +```xml + + newValue2 + newValue + value2 + value1 + + ``` + +Output JSON: + +```json +{ + resources: { + string: [ + { + key_name: 'key1', + '#text': 'value1' + }, + { + key_name: 'key2', + '#text': 'value2' + } + ] + } +} +``` + +### Chaining + +```js +import {XmlLocales} from 'xml-locales' + +const xmlData = ` + + value1 + value2 + +` + +const xmlLocales = new XmlLocales(xmlData) + +const jsonData = xmlLocales.add({key: 'newKey', value: 'newValue'}) +.add({key: 'newKey2', value: 'newValue2'}) +.update({oldValue: 'key1', newValue: 'firstKey'}) +.sort('desc') +.toXML() + +console.log(jsonData) +``` + +Output: + +```xml + + newValue2 + newValue + value2 + value1 + +``` + +## Packages + +| Package | version | +| ------- | -------- | +| 📦[xml-locales](https://github.com/Pisyukaev/xml-locales/tree/master/packages/xml-locales) | [![NPM](https://img.shields.io/npm/v/xml-locales.svg)](https://www.npmjs.com/package/xml-locales) | +| 💻[@xml-locales/cli](https://github.com/Pisyukaev/xml-locales/tree/master/packages/cli) | [![NPM](https://img.shields.io/npm/v/@xml-locales/cli.svg)](https://www.npmjs.com/package/@xml-locales/cli) |