README
:earth_africa: xd-loacalization-helper
A helper library making localization or internationalization of plugins for Adobe XD CC much easier.
Usage
Including the library
First, you'll need to include the library. This can be done in two ways:
- If you use a bundler like webpack and a package manager like npm, you can simply run
npm i xd-localization-helper
and get a reference to the helper by usingconst loc = require('xd-localization-helper');
in your JS. - If you don't use webpack and npm, you can also include the
localization-helper.js
file from the latest release in your project and get a reference to the helper by usingconst loc = require('./localization-helper')
.
Folder structure (the translations)
In your translations folder (which must be a direct subfolder of your plugin folder) specified when initializing the
helper, defaults to lang/
, you need at least a default.json
file for the library to work (if it's not there,
LocalizationHelper.load()
will reject). This should include all the default strings in case no translation is
provided for the actual language. This could look something like this:
{
"mainDialog.title": "My dialog",
"mainDialog.okBtnText": "Insert",
"mainDialog.cancelBtnText": "Cancel"
}
Additionally, you can provide translations for different languages by adding files corresponding to that language.
Their file names should match [language-code].json
, where [language-code]
is the language code according to
ISO 639-1.
To provide an example, we'll use German translations here (since German is the only other language I know and therefore
can demonstrate :wink:), which means we have to create a de.json
file in our tranlations folder which looks something
like this:
{
"mainDialog.title": "Mein Dialog",
"mainDialog.okBtnText": "Einfügen",
"mainDialog.cancelBtnText": "Abbrechen"
}
Likewise, a french translation would be a file called fr.json
etc.:
{
"mainDialog.title": "Mon pop-up",
"mainDialog.okBtnText": "Insérez",
"mainDialog.cancelBtnText": "Annuler"
}
Namespaced translations
Alternatively, you can also namespace your JSON with actual child objects instead of dots in the names. Therefore, instead of writing
{
"mainDialog.title": "Mein Dialog",
"mainDialog.okBtnText": "Einfügen",
"mainDialog.cancelBtnText": "Abbrechen"
}
you can also write
{
"mainDialog": {
"title": "Mein Dialog",
"okBtnText": "Einfügen",
"cancelBtnText": "Abbrechen"
}
}
The two versions are parsed identically (and therefore getting a translation works the same for both versions). Also, it is theoretically possible to mix both styles without it leading to problems, but I do not recommend this this as it makes the translations much more difficult to manage because of the inconsistencies.
It should be noted that the first version has a slightly better performance when getting the translation. However, the difference in performance (as long as you don't use 20+ levels of namespaces) is negligible.
JavaScript
In your JavaScript code, you first have to initialize the helper. Since we've put our JSON files into the default
folder lang
in this example, we simply achieve this by calling the asynchronous function LocalizationHelper.load()
:
const loc = require('xd-localization-helper');
async function initialize() {
await loc.load();
}
This load()
function returns a Promise which resolves when it loaded successfully and rejects with a message
informing you about what you did wrong in case something isn't correct (e.g., if there's no folder for the translations
or no default.json
exists).
After that, you can simply get the correct translation by using loc.get(key)
. For example,
loc.get('mainDialog.okBtnText')
would return 'Einfügen'
in a German environment, 'Insérez'
on a french OS and
'Insert'
on every other environment. Of course, you can specify as many translations as you'd like.
Further information
You can find further information (like usage examples, a full reference of the available functions and configuration options etc.) in the repo's wiki.