ioBroker adapter-dev

All dependencies an ioBroker adapter developer needs.

Installation

To use this library, add it to your dev dependencies:

npm install --save-dev @iobroker/adapter-dev

Add the following to the scripts section of your package.json:

  "scripts": {
    // ... other scripts before this
    "translate": "translate-adapter",
    // If you need to compile React or TypeScript:
    "build": "build-adapter",
  }

If you don't have any i18n JSON files yet, call the following exactly once:

npm run translate to-json

TL;DR

• You should only update i18n JSON files and you shouldn't touch words.js anymore.
• Add new strings only to the English JSON file.
• Call the following command whenever you add any text in JSON files (inside the admin i18n folder or in io-package.json).
  • If you have an HTML/JavaScript admin UI: npm run translate all
  • If you have a React admin UI: npm run translate
• Run the following commands to (re)compile your adapter:
  • If you are using TypeScript: npm run build-adapter typescript
  • If you have a React admin UI: npm run build-adapter react
  • If you have both: npm run build-adapter all

Manage Translations

With the above setup completed, you can use the different commands of translate-adapter simply by calling:

npm run translate <command>

The commands exist in three forms (all three will be shown as examples below):

• full name: a self-explaining name
• short code: a one-character command
• legacy name: the same name as previously used in gulp

In most cases, you don't need to specify any additional arguments as the defaults should match most adapters.

Note: if you need to provide arguments, you must add a double dash -- before any arguments!

npm run translate <command> -- <args>

Global Command Line Arguments

The following command line arguments can be passed to all commands:

• --io-package: Path to the io-package.json file. Short: -p. Default: ./io-package.json
• --admin: Path to the admin directory. Short: -a. Default: ./admin
• --words: Path to the words.js file. Short: -w. Default: searches it in the admin directory, either <admin-dir>/words.js or <admin-dir>/js/words.js.
• --base: Path to the english i18n file, multiple files are possible. Short: -b. Default: searches it in the admin directory, it will be <admin-dir>/i18n/en/translations.json or/and <admin-dir>/src/i18n/en.json
• --languages: Specify a subset of languages to be translated. Short -l. Default: all languages.

translate Command

This is the default command and does not need to be specified.

npm run translate                             # (default)
npm run translate translate                   # full name/legacy
npm run translate t                           # short code
npm run translate t -- -l de fr it            # Only translate into german, french and italian
npm run translate t -- --rebuild              # Delete all translation files and rebuild from scratch

Translates all not yet translated strings in io-package.json and the i18n JSON files to all supported languages using Google Translate.

Rebuild Option

npm run translate --rebuild                   # Delete all translation files and rebuild
npm run translate -r                          # Short form

The --rebuild option deletes all existing translation files (except English base files) and regenerates everything new. This is useful when:

• English source text has changed and you want fresh translations
• You want to ensure structural consistency across all translation files
• You've modified the English keys and want to clean up old translations

Previously known as gulp translate.

to-json Command

npm run translate to-json                     # full name
npm run translate j                           # short code
npm run translate adminWords2languages        # legacy

Converts words.js to the different i18n JSON files; this should be used exactly once when there are no JSON files yet.

Previously known as gulp adminWords2languages.

to-words Command

npm run translate to-words                    # full name
npm run translate w                           # short code
npm run translate adminLanguages2words        # legacy

Updates words.js from the different i18n JSON files; call this whenever you modify any of your JSON files manually. This is also automatically called by Weblate whenever translations are updated.

Previously known as gulp adminLanguages2words.

convert Command

npm run translate convert                     # full name
npm run translate c                           # short code

Converts old structure of i18n files, like i18n/LANG/translations.json to new one i18n/LANG.json. The new structure is preferred.

Additionally, it will convert the indent to 4 spaces, line endings to LF and sort the keys.

all Command

npm run translate all                         # full name
npm run translate a                           # short code
npm run translate translateAndUpdateWordsJS   # legacy

Calls translate and afterwards updates words.js using to-words followed by to-json.

Previously known as gulp translateAndUpdateWordsJS.

Environment Variables

Instead of Command Line Arguments

All command line arguments can also be provided as environment variables. Just prefix any argument with IOBROKER_TRANSLATE_:

• --io-package becomes IOBROKER_TRANSLATE_IO_PACKAGE
• --admin becomes IOBROKER_TRANSLATE_ADMIN
• --words becomes IOBROKER_TRANSLATE_WORDS
• --base becomes IOBROKER_TRANSLATE_BASE
• --languages becomes IOBROKER_TRANSLATE_LANGUAGES

Translate with Google Translate Credentials

If you wish to use the Google Translate V3 API, you can set the environment variable GOOGLE_APPLICATION_CREDENTIALS to point to a credentials file, so the translations can use larger quota for translations (which may result in costs).

The file can be generated on the Google Cloud Platform by creating a Service Account for Google Translate V3. See here for additional information. The expected format looks something like this:

{
    "type": "service_account",
    "project_id": "your-project-id-123456",
    "private_key_id": "1234567890abcdef1234567890abcdef12345678",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
    "client_email": "your-app-name@your-project-id-123456.iam.gserviceaccount.com",
    "client_id": "123456789012345678901",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/your-app-name%40your-project-id-123456.iam.gserviceaccount.com"
}

Translate with DeepL API

Recommended: If you wish to use the DeepL API for higher quality translations, you can set the environment variable DEEPL_API_KEY to your DeepL API key. DeepL generally provides better translation quality than Google Translate and has a generous free tier.

To get a DeepL API key:

1. Visit DeepL Pro Developer
2. Sign up for a free DeepL API account
3. Get your API key from the account dashboard
4. Set the environment variable: DEEPL_API_KEY=your-api-key-here

Example usage:

# Use DeepL for translation
export DEEPL_API_KEY="your-deepl-api-key"
npm run translate

Translation Service Priority

When multiple translation services are configured, the system automatically selects the best available service using this priority order:

1. DeepL API (when DEEPL_API_KEY is set) - Recommended for best quality
2. Google Translate V3 (when GOOGLE_APPLICATION_CREDENTIALS is set)
3. Legacy Google Translate (free, rate-limited)

Configure your preferred translation service using environment variables:

# For highest quality (recommended)
export DEEPL_API_KEY="your-deepl-api-key"
npm run translate

# For Google Translate V3
export GOOGLE_APPLICATION_CREDENTIALS="path/to/google-credentials.json"
npm run translate

Compile adapter files

The build-adapter command uses esbuild under the hood for lightning fast compilation. It has an extensive set of options you can use to fine tune the compilation process, although the defaults should work out of the box when the adapter was created with @iobroker/create-adapter:

npm run build typescript [options]      # TypeScript, full name
npm run build ts         [options]      # TypeScript, short code
npm run build react      [options]      # React
npm run build all        [options]      # Everything (at the moment this is TypeScript and React)

These options are available for all commands:

• --watch, short -w: Watch for changes and recompile

These only have an effect for the ts/typescript and all commands:

• --typescriptRootDir: Directory where the TypeScript part of the adapter is located. Default: .
• --typescriptOutDir: Directory where the compiled TypeScript output will be placed, relative to typescriptRootDir. Default: build
• --typescriptPattern: Glob pattern for TypeScript source files, relative to typescriptRootDir. Should not be changed unless bundling is enabled. Each match will result in a separate bundle. Default: src/**/*.ts
• --typescriptTsConfig: Path to the tsconfig.json file used for building TypeScript, relative to typescriptRootDir. Default: tsconfig.build.json
• --typescriptBundle: Bundle compiled TypeScript output into one file per entry point. Default: false
• --typescriptFormat: Format of the output file(s). CommonJS (cjs) or ES modules (esm).
• --typescriptCompileTarget: Compilation target for TypeScript. Determines which JS features will be used in the output file. Should be in sync with the minimum Node.js version supported by the adapter/ioBroker. Default: node12
• --typescriptRaw: An object of raw esbuild options that are passed to the build process for TypeScript. This has to be specified in a config file (see below). Default: (none)

These only have an effect for the react and all commands:

• --reactRootDir: Directory where the React part of the adapter is located. Default: admin
• --reactOutDir: Directory where the compiled React output will be placed, relative to reactRootDir. Default: build
• --reactWatchDir: Directory where the compiled React output will be placed in watch mode, relative to reactRootDir. Default: .watch
• --reactPattern: Glob pattern for React source files, relative to reactRootDir. Each match will result in a separate bundle. Default: src/{index,tab}.{tsx,jsx}
• --reactTsConfig: Path to the tsconfig.json file used for building React, relative to reactRootDir. Default: tsconfig.json
• --reactBundle: Bundle compiled React output into one file per entry point. Default: true
• --reactFormat: Format of the output file(s). Supports iife and esm, but ESM should only be selected when targeting modern browsers exclusively.
• --reactSplitting: Moves common code from multiple entry points into separate files, so they only have to be loaded once. Only relevant when reactBundle is true, reactFormat is "esm" and there are multiple entry points. If this is the case and there are unexpected differences between the watch mode and a normal build, try turning this off. Default: true
• --reactCompileTarget: Compilation target for React. Determines which JS features will be used in the output file. Default: es2018
• --reactRaw: An object of raw esbuild options that are passed to the build process for React. This has to be specified in a config file (see below). Default: (none)

Using a config file

By default, the build script looks for a .buildconfig.json file where the above options can be saved (without leading --), so they don't have to be specified on the command line. Example:

{ "typescriptBundle": true, "typescriptCompileTarget": "node16" }

This path can be changed with the --config option, short -c.

When using a .js file instead, this can be used to specify additional esbuild plugins, for example:

const { html } = require("@esbuilder/html");

module.exports = { reactRaw: { plugins: [html()] } };

clean-dir

This tool deletes a directory to be specified recursively.

npm run clean-dir <directory>                         # directory to remove

Changelog

1.5.0 (2025-09-20)

• (@Apollon77/@copilot) Add DeepL API support for higher quality translations. Set DEEPL_API_KEY environment variable to use DeepL as the preferred translation service. DeepL is prioritized over Google Translate when available.
• (@Apollon77/@copilot) Add remove-translations (rt) and remove-key (rk) commands for translation management. New commands allow removing translation keys from language files efficiently
• (@Apollon77/@copilot) Enhanced translation error messages for empty string keys with clearer error context and actionable guidance
• (@Apollon77/@copilot) Add --rebuild option to translate command for complete regeneration of translation files
• (@Apollon77/@copilot) Detect and preserve original indentation in JSON files during translation. Files using tab indentation or different space amounts are now preserved correctly instead of being converted to 4-space indentation.
• (@Apollon77/@copilot) Sort JSON keys alphabetically in all generated translation files
• (@Apollon77/@copilot) ESM support for TypeScript build format option. The --typescriptFormat option now accepts both cjs (CommonJS) and esm (ES modules) formats
• (@Apollon77/@copilot) Enhanced handling of rate limits for translations and persist as much progress as possible.

1.4.0 (2025-02-22)

• (ticaki) rimraf replaced by by internal tool.
• (hombach) change year to 2025
• (hombach) Fix two vulnerabilities
• (hombach) Bump dev dependencies
• (hombach) add tests for node.js 22, remove node 16 tests
• (@GermanBluefox) Added convert command to convert old i18n structure to new one
• (@GermanBluefox) Packages were updated
• (@UncleSamSwiss) Change default path for translation JSON files to admin/i18n/en.json; the old path is still supported for existing repositories

1.3.0 (2024-02-18)

• (kleinOr/Apollon77) Detects and keeps space indentation of io-package
• (Steiger04) Fix handling of dot keys for esbuild
• (Steiger04) Update esbuild and adjust watch mode
• (Steiger04) process.env.NODE_ENV is now also available server side

1.2.0 (2022-10-23)

• (Grizzlebee) only translate linkText from messages if existent
• (Apollon77) Add ukrainian as language for translations

1.1.0 (2022-09-14)

• (Grizzelbee) Also translate admin messages in io-package.json
• (AlCalzone) support specifying raw esbuild options, like loaders/plugins

1.0.1 (2022-08-17)

• (Apollon77) make sure that also texts with multiple sentences are correctly translated via Google Translate

1.0.0 (2022-02-15)

• (AlCalzone) Add build script to compile TypeScript and React using the blazing fast esbuild

0.1.0 (2021-09-21)

• (UncleSamSwiss) Removed dependency on gulp
• (UncleSamSwiss) Rewrote translation management as a regular Node.js application

0.0.4 (2021-05-26)

• (UncleSamSwiss) Implemented gulp tasks very similar to the existing tasks

0.0.3 (2021-05-06)

• (UncleSamSwiss) Fixed npm publishing

0.0.2 (2021-05-06)

• (UncleSamSwiss) Initial repository setup