# @tappytaps/translation-tool

> Generates platform specific string resources (iOS, Android and Web) from xlsx files.

Latest version **2.0.1** (published 2025-08-05) · ISC license · 0 weekly downloads

## Install

```sh
npm install @tappytaps/translation-tool
pnpm add @tappytaps/translation-tool
yarn add @tappytaps/translation-tool
bun add @tappytaps/translation-tool
```

Provides the command `stringsgen`.

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2025-08-05 |
| First published | 2018-11-30 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 22 |
| Unpacked size | 43.8 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | sarsonj, bouralu89 |

## Links

- npm: https://www.npmjs.com/package/@tappytaps/translation-tool
- npm.io page: https://npm.io/package/@tappytaps/translation-tool

## Dependencies (22)

- [rc](https://npm.io/package/rc.md) ^1.2.8
- [ora](https://npm.io/package/ora.md) ^3.4.0
- [xlsx](https://npm.io/package/xlsx.md) ^0.18.5
- [axios](https://npm.io/package/axios.md) ^1.10.0
- [chalk](https://npm.io/package/chalk.md) ^4.1.2
- [table](https://npm.io/package/table.md) ^6.9.0
- [xliff](https://npm.io/package/xliff.md) ^6.2.2
- [yargs](https://npm.io/package/yargs.md) ^12.0.5
- [ollama](https://npm.io/package/ollama.md) ^0.5.15
- [openai](https://npm.io/package/openai.md) ^4.98.0
- [fs-extra](https://npm.io/package/fs-extra.md) ^7.0.1
- [inquirer](https://npm.io/package/inquirer.md) ^12.6.1
- [commander](https://npm.io/package/commander.md) ^14.0.0
- [form-data](https://npm.io/package/form-data.md) ^4.0.3
- [iso-639-1](https://npm.io/package/iso-639-1.md) ^3.1.5
- [node-xlsx](https://npm.io/package/node-xlsx.md) ^0.12.2
- [pretty-format](https://npm.io/package/pretty-format.md) ^30.0.2
- [xlsx-js-style](https://npm.io/package/xlsx-js-style.md) ^1.2.0
- [stream-buffers](https://npm.io/package/stream-buffers.md) ^3.0.3
- [fast-xml-parser](https://npm.io/package/fast-xml-parser.md) ^5.2.5
- [follow-redirects](https://npm.io/package/follow-redirects.md) ^1.12.1
- [i18n-strings-files](https://npm.io/package/i18n-strings-files.md) ^2.0.0

## Recent versions

- 2.0.1 (latest) — 2025-08-05
- 2.0.2-beta.2 (beta) — 2025-09-01
- 2.0.2-beta.1 — 2025-08-05
- 2.0.0 — 2025-07-24
- 2.0.0-beta.12 — 2025-07-24
- 2.0.0-beta.11 — 2025-07-17
- 2.0.0-beta.10 — 2025-07-15
- 2.0.0-beta.9 — 2025-07-15
- 2.0.0-beta.8 — 2025-07-15
- 2.0.0-beta.7 — 2025-07-15
- 2.0.0-beta.6 — 2025-06-10
- 2.0.0-beta.5 — 2025-06-09
- 2.0.0-beta.4 — 2025-06-03
- 2.0.0-beta.3 — 2025-06-03
- 2.0.0-beta.2 — 2025-06-02
- … 46 more at https://npm.io/package/@tappytaps/translation-tool/versions

## README

# translation-tool

Generates platform specific string resources (iOS, Android and Web) from xlsx files.

# Installation

```
npm i @tappytaps/translation-tool
```

# How to use it?

Go to your project:

```
$ cd path/to/your/project
```

Create and define configuration file:

```
$ touch .stringsgenrc
$ code .stringsgenrc
```

Run strings generator:

```
$ stringsgen generate
```

Upload strings to Weblate:

```
$ stringsgen upload-strings
```

Upload plurals to Weblate:

```
$ stringsgen upload-plurals
```

Download translated strings from Weblate:

```
$ stringsgen download
```

Check not used strings on Weblate:

```
$ stringsgen check
```

# Configuration

You provide your configuration via .stringsgenrc file.

```json
{
    "xlsxUrl": "YOUR_XLSX_FILE_URL",
    "weblateUrl": "YOUR_WEBLATE_URL",
    "platform": "ios",
    "outputDir": ".",
    "outputName": "Localizable.strings",
    "webParameterType": "value",
    "baseLanguage": "en",
    "languages": ["en", "cs", "it"],
    "columns": {
        "id": "id",
        "key": "key",
        "isFinal": "is_final",
        "isHtml": "is_html",
        "allowDuplicates": "allow_duplicates",
        "description": "description"
    },
    "sheets": [
        {
            "name": "YOUR_SHEET_NAME",
            "valueColumn": "value",
            "weblateProjectSlug": "YOUR_PROJECT_SLUG",
            "weblateComponentSlug": "YOUR_COMPONENT_SLUG"
        }
    ],
    "plurals": {
        "sourceFile": "./Localizable.stringsdict",
        "weblateProjectSlug": "YOUR_PROJECT_SLUG",
        "weblateComponentSlug": "YOUR_COMPONENT_SLUG"
    }
}
```

You also need to set these environment variables:

```bash
export WEBLATE_API_KEY="your_api_key"
```

- **xlsxUrl**
    - URL to XLSX file with strings
- **weblateUrl**
    - URL of your Weblate instance
- **platform**
    - values: ios, android, web
- **outputDir**
    - the destination where strings will be downloaded or generated
- **outputName**
    - the filename of generated or downloaded files
- **webParameterType**
    - only for web
    - values: value, tag
    - default: value
- **baseLanguage**
    - language of source strings in xlsx sheet
- **languages**
    - supported languages that will be downloaded from Weblate
- **columns**
    - names of columns in each sheet
    - **id**: unique string IDs, will be used for Weblate upload
    - **key**:
        - string keys
        - will be used on platform when downloading or generating strings
        - must be unique, otherwise the strings generator will end with error
    - **isFinal**: TRUE/FALSE, only final strings will be uploaded to Weblate
    - **isHtml**:
        - TRUE/FALSE, if string contains HTML tags
        - the strings generator will handle a string value in special way (Android)
    - **allowDuplicates**: if the column contains **TRUE**, the strings generator will not show warnings for duplicate in values column for given string
    - **aiTranslationDescription**: description of the string for AI translations.
- **sheets**
    - mapping of XLSX sheets to Weblate projects
    - **name**: sheet name
    - **valueColumn**: column name with strings values
    - **weblateProjectSlug**: Weblate project slug
    - **weblateComponentSlug**: Weblate component slug
- **plurals**
    - **sourceFile**: source file with plural strings, the file will be uploaded to Weblate
    - **weblateProjectSlug**: Weblate project slug
    - **weblateComponentSlug**: Weblate component slug

# Spreadsheet requirements

This tool works only with xlsx file format. The easiest way how to create and publish your spreadsheet is using Google Spreadsheet. In `File/Publish to the web...` you choose xlsx file format and put the link in your config file. You can make copy of sample spreadsheet [here](https://docs.google.com/spreadsheets/d/1Jwpwu6p4cFy8rMRmxHO9r5ft8NO86FwFGDMLVneNCTI/edit?ts=5c10d990#gid=0), just use `File/Make a copy...`.

The sample spreadsheet contains prepared autoincrement id generator. If you want to use this id generator, go to `Tools/Script editor`, update script to respect your column and sheet names by changing values of `idsColumnName`, `valuesColumnName` and `sheetNames` variables. Then go to `Current project's triggers` (the clock icon in tool bar) and create a new trigger for event type _On change_ (as function to run select _onChange_).

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