# @warren-bank/translate-subtitles > Command-line utility to use an online language translation service to automate the localization of subtitle text files. Latest version **3.0.0** (published 2025-11-07) · GPL-2.0 license · 0 weekly downloads ## Install ```sh npm install @warren-bank/translate-subtitles pnpm add @warren-bank/translate-subtitles yarn add @warren-bank/translate-subtitles bun add @warren-bank/translate-subtitles ``` Provides the command `translate-subtitles`. ## Health **Score 45/100 (D)** — status: stable. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. ## Facts | | | |---|---| | Version | 3.0.0 | | Published | 2025-11-07 | | First published | 2020-12-26 | | Weekly downloads | 0 | | License | GPL-2.0 | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 3 | | Unpacked size | 45.6 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Warren R. Bank | | Maintainers | warren-r-bank | ## Links - npm: https://www.npmjs.com/package/@warren-bank/translate-subtitles - Repository: https://github.com/warren-bank/node-translate-subtitles - Homepage: https://github.com/warren-bank/node-translate-subtitles#readme - Issues: https://github.com/warren-bank/node-translate-subtitles/issues - npm.io page: https://npm.io/package/@warren-bank/translate-subtitles ## Dependencies (3) - [@warren-bank/mkdir-sync](https://npm.io/package/@warren-bank/mkdir-sync.md) ^1.0.2 - [@warren-bank/node-process-argv](https://npm.io/package/@warren-bank/node-process-argv.md) ^1.2.2 - [@warren-bank/multiapi-language-translator](https://npm.io/package/@warren-bank/multiapi-language-translator.md) ^1.1.0 ## Recent versions - 3.0.0 (latest) — 2025-11-07 - 2.0.0 — 2025-04-19 - 1.0.1 — 2023-05-27 - 1.0.0 — 2020-12-26 ## README ### [translate-subtitles](https://github.com/warren-bank/node-translate-subtitles) Command-line utility to use an online language translation service to automate the localization of subtitle text files. #### Features: * supports the following subtitle text file formats: - srt - vtt #### Limitations: * produces translated subtitle text files that contain no style tags #### Requirements: * access to a server hosting one of the supported language translation service APIs - [LibreTranslate](https://github.com/LibreTranslate/LibreTranslate#mirrors) * API key * API URL - [DeepL](https://www.deepl.com/en/pro-api) * API key #### Supported Languages * the list of supported input and output languages depends upon the chosen API - [LibreTranslate](https://github.com/warren-bank/node-libre-language-translator#supported-languages) * there is no guarantee for consistency, either between server instances or over time * to obtain a real-time list of supported languages from a specific server instance, directly query its `/languages` [API](https://libretranslate.com/docs) endpoint - [DeepL](https://github.com/warren-bank/node-deepl-language-translator#supported-input-languages) #### Installation: ```bash npm install --global @warren-bank/translate-subtitles ``` #### Usage: ```bash translate-subtitles options: ======== "-h" "--help" Print a help message describing all command-line options. "-v" "--version" Display the version. "-s" "--api-service" [required] Name of language translation service API. enum: "libre", "deepl" "-k" "--api-key" [optional] API key. Fallback for "libre" service: Value of the "LIBRE_TRANSLATE_API_KEY" environment variable, if one exists. Fallback for "deepl" service: Value of the "DEEPL_TRANSLATE_API_KEY" environment variable, if one exists. "-u" "--api-url" [optional] API URL. Fallback for "libre" service: Value of the "LIBRE_TRANSLATE_API_URL" environment variable, if one exists. Fallback for "deepl" service: Value of the "DEEPL_TRANSLATE_API_URL" environment variable, if one exists. Default for "libre" service: "https://libretranslate.com" Default for "deepl" service for free accounts: "https://api-free.deepl.com/v2" Default for "deepl" service for paid accounts: "https://api.deepl.com/v2" "-i" "--input-language" [required] Language code for input file. "-o" "--output-language" [optional] Language code for output file. note: This flag can be repeated to produce multiple output files. note: Input language is ignored. Default: Produce output files for all languages. "-I" "--input-path" [required] Filesystem path to input subtitle text file, or Filesystem path to input directory containing subtitle text file(s). "-O" "--output-path" [optional] Filesystem path to output directory. Default: Same as the input path. Note: For each output language: - output file is written in output directory - output filename extension includes language code (ex: '/out/file.de.srt', '/out/file.zh-TW.srt') "-r" "--recurse-input-dirs" [optional] Search for subtitle text files within input path subdirectories. Precondition: Input path is a directory. Default: disabled "-m" "--mirror-input-dirs" [optional] Mirror relative input directory paths to output directory. Precondition: Input path is a directory. Precondition: Input path recursion is enabled. Default: disabled "--nr" "--no-replace" "--no-clobber" [optional] Skip output languages for which the output file already exists. Default: Disabled. Overwrite if exists. "--nb" "--no-break" "--no-break-on-error" [optional] When translating multiple output languages and one encounters an error, print a log statement and continue processing the remaining output languages. Default: Disabled. The library throws an error, and the command-line utility exits with code. "-d" "--debug" [optional] Writes raw data files to output directory. note: If enabled, then for each language: - output file is written in output directory - output filename extension includes language code (ex: '/out/debug.en.txt', '/out/debug.de.txt', '/out/debug.zh-TW.txt') - file with the input language code contains the list of parsed strings - file with an output language code contains the list of translated strings Default: disabled ``` #### Examples: 1. [example](./tests/libre/01): single subtitle text file - use LibreTranslate service API - translate to all supported languages - save translations in different output directory 2. [example](./tests/libre/02): single subtitle text file - use LibreTranslate service API - translate to one specific language - save translation in different output directory 3. [example](./tests/libre/03): single subtitle text file - use LibreTranslate service API - translate to one specific language - save translation in same directory 4. [example](./tests/libre/04): single directory with multiple subtitle text files - use LibreTranslate service API - translate to one specific language - save translations in different output directory 5. [example](./tests/libre/05): single directory with multiple subtitle text files - use LibreTranslate service API - translate to one specific language - save translations in same directory 6. [example](./tests/libre/06): nested directory tree with multiple subtitle text files - use LibreTranslate service API - translate to one specific language - recurse into input subdirectories - save translations in different output directory without mirroring * warning: - this operation could result in output filename collisions * non-unique filenames are assigned a sequentially increasing numeric index * for example: - `/out/file.de.srt` - `/out/file.2.de.srt` - `/out/file.3.de.srt` 7. [example](./tests/libre/07): nested directory tree with multiple subtitle text files - use LibreTranslate service API - translate to one specific language - recurse into input subdirectories - save translations in different output directory with mirroring #### Legal: * copyright: [Warren Bank](https://github.com/warren-bank) * license: [GPL-2.0](https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt) --- _Source: https://npm.io/package/@warren-bank/translate-subtitles · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._