{"id":16786455,"url":"https://github.com/pklaschka/xd-localization-helper","last_synced_at":"2025-03-22T00:32:33.794Z","repository":{"id":33703638,"uuid":"160838421","full_name":"pklaschka/xd-localization-helper","owner":"pklaschka","description":"A library making localization for plugins for Adobe XD CC easy.","archived":false,"fork":false,"pushed_at":"2024-04-23T04:13:22.000Z","size":1401,"stargazers_count":3,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-18T06:35:55.502Z","etag":null,"topics":["adobe","adobe-xd","dialogs","helper","internationalization","library","localization","plugin","plugins","xd"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pklaschka.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-07T15:04:13.000Z","updated_at":"2024-04-10T12:22:46.000Z","dependencies_parsed_at":"2024-01-09T02:59:45.966Z","dependency_job_id":"6d3f2ef5-3c23-4d6d-8e86-ca566c01d35a","html_url":"https://github.com/pklaschka/xd-localization-helper","commit_stats":{"total_commits":285,"total_committers":4,"mean_commits":71.25,"dds":0.3157894736842105,"last_synced_commit":"3c26f1f77af470175f73e2bfa30e4118bd5d5169"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pklaschka%2Fxd-localization-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pklaschka%2Fxd-localization-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pklaschka%2Fxd-localization-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pklaschka%2Fxd-localization-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pklaschka","download_url":"https://codeload.github.com/pklaschka/xd-localization-helper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244890102,"owners_count":20527030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adobe","adobe-xd","dialogs","helper","internationalization","library","localization","plugin","plugins","xd"],"created_at":"2024-10-13T08:12:17.488Z","updated_at":"2025-03-22T00:32:33.530Z","avatar_url":"https://github.com/pklaschka.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# :earth_africa: xd-loacalization-helper\n\n[![Build Status](https://travis-ci.com/pklaschka/xd-localization-helper.svg?branch=master)](https://travis-ci.com/pklaschka/xd-localization-helper)\n[![npm version](https://badge.fury.io/js/xd-localization-helper.svg)](https://badge.fury.io/js/xd-localization-helper)\n[![GitHub Release Date](https://img.shields.io/github/release-date/pklaschka/xd-localization-helper.svg)](https://github.com/pklaschka/xd-localization-helper/releases)\n[![GitHub](https://img.shields.io/github/license/pklaschka/xd-localization-helper.svg)](https://github.com/pklaschka/xd-localization-helper/blob/master/LICENSE)\n[![npm bundle size (minified)](https://img.shields.io/bundlephobia/min/xd-localization-helper.svg)](https://www.npmjs.com/package/xd-localization-helper)\n\n\n\n[![NPM](https://nodei.co/npm/xd-localization-helper.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/xd-localization-helper/)\n\n\n---\n\nA helper library making localization or internationalization of plugins for Adobe XD CC much easier.\n\n### Usage\n\n#### Including the library\n\nFirst, you'll need to include the library. This can be done in two ways:\n1. If you use a bundler like webpack and a package manager like npm, you can simply run `npm i xd-localization-helper` \nand get a reference to the helper by using `const loc = require('xd-localization-helper');` in your JS.\n2. If you don't use webpack and npm, you can also include the `localization-helper.js` file from the latest \n[release](https://github.com/pklaschka/xd-localization-helper/releases) in your project and get a reference to the \nhelper by using `const loc = require('./localization-helper')`.\n\n#### Folder structure (the translations)\n\nIn your translations folder (which must be a direct subfolder of your plugin folder) specified when initializing the \nhelper, defaults to `lang/`, you need at least a `default.json` file for the library to work (if it's not there, \n`LocalizationHelper.load()` will reject). This should include all the default strings in case no translation is \nprovided for the actual language. This could look something like this:\n\n```json\n{\n    \"mainDialog.title\": \"My dialog\",\n    \"mainDialog.okBtnText\": \"Insert\",\n    \"mainDialog.cancelBtnText\": \"Cancel\"\n}\n```\n\nAdditionally, you can provide translations for different languages by adding files corresponding to that language. \nTheir file names should match `[language-code].json`, where `[language-code]` is the language code according to \n[ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).\n\nTo provide an example, we'll use German translations here (since German is the only other language I know and therefore \ncan demonstrate :wink:), which means we have to create a `de.json` file in our tranlations folder which looks something \nlike this:\n\n```json\n{\n    \"mainDialog.title\": \"Mein Dialog\",\n    \"mainDialog.okBtnText\": \"Einfügen\",\n    \"mainDialog.cancelBtnText\": \"Abbrechen\"\n}\n```\nLikewise, a french translation would be a file called `fr.json` etc.:\n\n```json\n{\n    \"mainDialog.title\": \"Mon pop-up\",\n    \"mainDialog.okBtnText\": \"Insérez\",\n    \"mainDialog.cancelBtnText\": \"Annuler\"\n}\n```\n\n#### Namespaced translations\nAlternatively, you can also namespace your JSON with actual child objects instead of dots in the names. Therefore, \ninstead of writing \n\n```json\n{\n    \"mainDialog.title\": \"Mein Dialog\",\n    \"mainDialog.okBtnText\": \"Einfügen\",\n    \"mainDialog.cancelBtnText\": \"Abbrechen\"\n}\n```\n\nyou can also write \n\n```json\n{\n  \"mainDialog\": {\n    \"title\": \"Mein Dialog\",\n    \"okBtnText\": \"Einfügen\",\n    \"cancelBtnText\": \"Abbrechen\"  \n  }\n}\n```\n\nThe two versions are parsed identically (and therefore getting a translation works the same for both versions). Also, \nit is theoretically possible to mix both styles without it leading to problems, but I do not recommend this this as it\nmakes the translations much more difficult to manage because of the inconsistencies.\n\nIt should be noted that the first version has a slightly better performance when getting the translation. However, the\ndifference in performance (as long as you don't use 20+ levels of namespaces) is negligible.\n\n#### JavaScript\n\nIn your JavaScript code, you first have to initialize the helper. Since we've put our JSON files into the default \nfolder `lang` in this example, we simply achieve this by calling the asynchronous function `LocalizationHelper.load()`:\n\n```javascript\nconst loc = require('xd-localization-helper');\n\nasync function initialize() {\n    await loc.load();    \n}\n```\n\nThis `load()` function returns a Promise which resolves when it loaded successfully and rejects with a message \ninforming you about what you did wrong in case something isn't correct (e.g., if there's no folder for the translations \nor no `default.json` exists).\n\nAfter that, you can simply get the correct translation by using `loc.get(key)`. For example, \n`loc.get('mainDialog.okBtnText')` would return `'Einfügen'` in a German environment, `'Insérez'` on a french OS and \n`'Insert'` on every other environment. Of course, you can specify as many translations as you'd like.\n\n### Further information\n\nYou can find further information (like usage examples, a full reference of the available functions and configuration \noptions etc.) in the [repo's wiki](https://github.com/pklaschka/xd-localization-helper/wiki).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpklaschka%2Fxd-localization-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpklaschka%2Fxd-localization-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpklaschka%2Fxd-localization-helper/lists"}