# xml-locales

> Tool for locales in xml files

Latest version **1.0.0** (published 2024-02-13) · 0 weekly downloads

## Install

```sh
npm install xml-locales
pnpm add xml-locales
yarn add xml-locales
bun add xml-locales
```

## Health

**Score 45/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2024-02-13 |
| First published | 2023-11-20 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 26.2 KB |
| Known vulnerabilities | 0 (+6 in 1 direct dependencies) |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Maintainers | pisyukaev |
| Keywords | xml-locales, xml, locales |

## Links

- npm: https://www.npmjs.com/package/xml-locales
- Repository: https://github.com/Pisyukaev/xml-locales
- Homepage: https://github.com/Pisyukaev/xml-locales#readme
- Issues: https://github.com/Pisyukaev/xml-locales/issues
- npm.io page: https://npm.io/package/xml-locales

## Dependencies (2)

- [xml-formatter](https://npm.io/package/xml-formatter.md) 3.6.0
- [fast-xml-parser](https://npm.io/package/fast-xml-parser.md) 4.3.2

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2024-02-13
- 0.0.5 — 2023-12-05
- 0.0.4 — 2023-11-23
- 0.0.3 — 2023-11-23
- 0.0.2 — 2023-11-21
- 0.0.1 — 2023-11-21
- 0.0.0 — 2023-11-20

## README

# 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
> <resources>
>   <string name="key1">value1</string>
>   <string name="key2">value2</string>
> </resources> 
>```

## 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 = `
<resources>
  <string name="key1">value1</string>
  <string name="key2">value2</string>
</resources>
`

const xmlLocales = new XmlLocales(xmlData)
const jsonData = xmlLocales.add({keys: ['newKey'], values: ['newValue']}).toXML()

console.log(jsonData)
```

Output:

```xml
<resources>
   <string name="key1">value1</string>
   <string name="key2">value2</string>
   <string name="newKey">newValue</string>
</resources>
```

### Update key/value

```js
import {XmlLocales} from 'xml-locales'

const xmlData = `
<resources>
  <string name="key1">value1</string>
  <string name="key2">value2</string>
</resources>
`

const xmlLocales = new XmlLocales(xmlData)
const jsonData = xmlLocales.add({keys: ['newKey'], values: ['newValue']})
.update({oldValues: ['key1'], newValues: ['firstKey']})
.update({oldValues: ['value2'], newValues: ['secondValue']})
.toXML()

console.log(jsonData)
```

Output:

```xml
<resources>
   <string name="firstKey">value1</string>
   <string name="key2">secondValue</string>
</resources>
```

### Delete by key/value

```js
import {XmlLocales} from 'xml-locales'

const xmlData = `
<resources>
  <string name="key1">value1</string>
  <string name="key2">value2</string>
</resources>
`

const xmlLocales = new XmlLocales(xmlData)
const jsonData = xmlLocales.add({keys: ['newKey'], values: ['newValue']})
.deleteByKey('key1')
.deleteByValue('value2')
.toXML()

console.log(jsonData)
```

Output:

```xml
<resources>
</resources>
```

### XML and JSON

```js
import {XmlLocales} from 'xml-locales'

const xmlData = `
<resources>
  <string name="key1">value1</string>
  <string name="key2">value2</string>
</resources>
`

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
<resources>
  <string name="newKey2">newValue2</string>
  <string name="newKey">newValue</string>
  <string name="key2">value2</string>
  <string name="firstKey">value1</string>
</resources>
 ```

Output JSON:

```json
{
 "resources": {
  "string": [
   {
    "key_name": "key1",
    "#text": "value1"
   },
   {
    "key_name": "key2",
    "#text": "value2"
   }
  ]
 }
}
```

### Chaining

```js
import {XmlLocales} from 'xml-locales'

const xmlData = `
<resources>
  <string name="key1">value1</string>
  <string name="key2">value2</string>
</resources>
`

const xmlLocales = new XmlLocales(xmlData)

const jsonData = xmlLocales.add({keys: ['newKey'], values: ['newValue']})
.add({keys: ['newKey2'], values: ['newValue2']})
.update({oldValues: ['key1'], newValues: ['firstKey']})
.sort('desc')
.toXML()

console.log(jsonData)
```

Output:

```xml
<resources>
  <string name="newKey2">newValue2</string>
  <string name="newKey">newValue</string>
  <string name="key2">value2</string>
  <string name="firstKey">value1</string>
</resources>
```

## 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)  |

---
_Source: https://npm.io/package/xml-locales · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._