'xd-localization-helper' – a library for plugin localization

I’ve just released another open-source library: xd-localization-helper. This makes it very easy to localize dialogs and other elements of your plugins.

To use it, you’ll need to either install it via npm (npm i xd-localization-helper) and get a reference to it via

const loc = require('xd-localization-helper');

or you can copy the localization-helper.js file from the latest release into your project and reference it with

const loc = require('./localization-helper');

Then, you simply need to create a lang folder in your plugin’s root folder (the same level as your manifest.json), which contains a default.json file with all the strings you want to use. If you then put translation files [language-code].json into this directory, the library will automatically use them. These JSON files shall contain your strings in a key-value-form. Here’s an example:

    "mainDialog.title": "My dialog"

Then, you just have to initialize the library by calling the asynchronous function await loc.load() and you’re good to go. Just get the correct translation (or – if none exists – the default value) by calling loc.get(key), where key is the id of the string in your JSON file.

There are many advantages when using the library:

  • You can easily manage many translations since this way of storing translations is pretty standard and supported by many editors, e.g., BabelEdit (this is no advertisement for this editor, but just the editor I personally use :wink:)
  • there are many configuration options like e.g., “forcing” a specific language (if, for example, you allow selecting a language in your plugin’s preferences)
  • A declarative style of defining strings (with all the advantages that come along with it :wink:)

The whole library is MIT-Licensed, can be found on GitHub and on npm. You can find much more detailed instructions on how to use it in the Readme and a full reference on all the available methods and configuration options in the repo’s wiki.

I’ve also used TDD, tested it a lot in a real plugin etc., so it should be stable and ready for you to use. However, if you find any issues, just open an issue on GitHub and I’ll look into it.


TL;DR :wink::

A library for localization of plugins for XD (e.g., dialogs), hosted on GitHub and npm (called xd-localization-helper) automating otherwise cumbersome tasks of localizing a plugin and making it easier to manage many translations…

Wow – that “escalated” rather quickly (for a library for plugins for XD :wink:)…



I’ve just released a new version: v1.1.0.

It is the best kind of release: new features without any breaking changes. The new release adds support for namespaced translations (improving readability of your JSON files as well as the support of editors like BabelEdit etc.). You can find more information about the namespaced translations in the repo’s readme.

The new release is available – as always via npm as well as on GitHub and you can find the full release notes at https://github.com/pklaschka/xd-localization-helper/releases/tag/v1.1.0.

Happy coding :wink: