Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pklaschka/xd-localization-helper
A library making localization for plugins for Adobe XD CC easy.
https://github.com/pklaschka/xd-localization-helper
adobe adobe-xd dialogs helper internationalization library localization plugin plugins xd
Last synced: 3 months ago
JSON representation
A library making localization for plugins for Adobe XD CC easy.
- Host: GitHub
- URL: https://github.com/pklaschka/xd-localization-helper
- Owner: pklaschka
- License: mit
- Created: 2018-12-07T15:04:13.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2024-04-23T04:13:22.000Z (9 months ago)
- Last Synced: 2024-10-13T08:12:51.591Z (4 months ago)
- Topics: adobe, adobe-xd, dialogs, helper, internationalization, library, localization, plugin, plugins, xd
- Language: JavaScript
- Size: 1.34 MB
- Stars: 3
- Watchers: 3
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# :earth_africa: xd-loacalization-helper
[](https://travis-ci.com/pklaschka/xd-localization-helper)
[](https://badge.fury.io/js/xd-localization-helper)
[](https://github.com/pklaschka/xd-localization-helper/releases)
[](https://github.com/pklaschka/xd-localization-helper/blob/master/LICENSE)
[](https://www.npmjs.com/package/xd-localization-helper)
[](https://nodei.co/npm/xd-localization-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:
1. 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 using `const loc = require('xd-localization-helper');` in your JS.
2. If you don't use webpack and npm, you can also include the `localization-helper.js` file from the latest
[release](https://github.com/pklaschka/xd-localization-helper/releases) in your project and get a reference to the
helper by using `const 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:
```json
{
"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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
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:
```json
{
"mainDialog.title": "Mein Dialog",
"mainDialog.okBtnText": "Einfügen",
"mainDialog.cancelBtnText": "Abbrechen"
}
```
Likewise, a french translation would be a file called `fr.json` etc.:
```json
{
"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
```json
{
"mainDialog.title": "Mein Dialog",
"mainDialog.okBtnText": "Einfügen",
"mainDialog.cancelBtnText": "Abbrechen"
}
```
you can also write
```json
{
"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()`:
```javascript
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](https://github.com/pklaschka/xd-localization-helper/wiki).