{"id":23909181,"url":"https://github.com/ilib-js/ilib-loctool-pendo-md","last_synced_at":"2026-05-16T04:48:12.249Z","repository":{"id":255704456,"uuid":"853075536","full_name":"iLib-js/ilib-loctool-pendo-md","owner":"iLib-js","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-12T12:21:46.000Z","size":206,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-05T05:17:14.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iLib-js.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2024-09-06T00:14:36.000Z","updated_at":"2024-12-12T12:21:49.000Z","dependencies_parsed_at":"2024-12-12T13:26:30.501Z","dependency_job_id":"cb7f4d1c-6c31-4000-93f3-eb45444bc80c","html_url":"https://github.com/iLib-js/ilib-loctool-pendo-md","commit_stats":null,"previous_names":["wadimw/ilib-loctool-pendo-md","ilib-js/ilib-loctool-pendo-md"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loctool-pendo-md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loctool-pendo-md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loctool-pendo-md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loctool-pendo-md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iLib-js","download_url":"https://codeload.github.com/iLib-js/ilib-loctool-pendo-md/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240339598,"owners_count":19785957,"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":[],"created_at":"2025-01-05T05:17:23.872Z","updated_at":"2026-05-16T04:48:12.236Z","avatar_url":"https://github.com/iLib-js.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e :warning: **Deprecation Notice** :warning:\n\u003e This repository has been deprecated. Please use the corresponding package from the [iLib-js monorepo](https://github.com/iLib-js/ilib-mono) instead.\n\n# ilib-loctool-pendo-md\n\n[Loctool](https://github.com/iLib-js/loctool) plugin to handle translation strings exported from [Pendo](https://www.pendo.io/).\n\nThis plugin accepts an XLIFF file exported from Pendo (`\u003cxliff version=\"1.2\"\u003e\u003cfile datatype=\"pendoguide\"\u003e`) and extracts existing translation units from it mapping them 1:1 to loctool Resources with **escaped Markdown syntax**.\n\n## Extraction\n\n### Markdown Syntax\n\nAs per [Pendo documentation](https://support.pendo.io/hc/en-us/articles/360031866552-Use-markdown-syntax-for-guide-text-styling), the app supports a subset of classic Markdown syntax:\n\n```md\n_italics_ or _italics_\n**bold**\n[links](example.com)\n\n1. ordered lists\n\n-   unordered lists\n\n*   unordered lists\n\n-   unordered lists\n```\n\nAnd some custom extensions:\n\n```md\n~~Strikethrough~~\n++Underline++\n{color: #000000}colored text{/color}\n```\n\nThere is a high risk of breaking this syntax by translators, so the main task of this plugin is to **escape** this syntax using XML-like component tags `\u003cc0\u003e\u003c/c0\u003e`.\n\n### Escaping\n\nGiven a Pendo markdown string like\n\n```markdown\nString with _emphasis_, ++underline++, {color: #FF0000}colored text{/color} and [a link](https://example.com)\n```\n\ntransform it to an escaped string\n\n```text\nString with \u003cc0\u003eemphasis\u003c/c0\u003e, \u003cc1\u003eunderline\u003c/c1\u003e, \u003cc2\u003ecolor\u003c/c2\u003e and \u003cc3\u003ea link\u003c/c3\u003e\n```\n\n### Unescaping (backconversion)\n\nAfter parsing a source string, plugin keeps track of escaped components:\n\n```text\n- c0: emphasis\n- c1: underline\n- c2: color #FF0000\n- c3: link https://example.com\n```\n\nThanks to that, during localization this plugin is able to **unescape** (backconvert) these components in a translated string:\n\n```text\nTranslated string, \u003cc3\u003etranslated link\u003c/c3\u003e \u003cc1\u003etranslated underline\u003c/c1\u003e, \u003cc0\u003etranslated emphasis\u003c/c0\u003e \u003cc2\u003etranslated color\u003c/c2\u003e\n```\n\nit will transform it back to the markdown syntax\n\n```markdown\nTranslated string, [translated link](example.com) ++translated underline++, _translated emphasis_ {color: $FF0000}translated color{/color}\n```\n\nNote that it supports shuffled order of components, since this is often required in different languages.\n\n## Translation\n\nDuring the _localize_ step, this plugin will output a copy of the original Pendo XLIFF for each locale defined in the loctool's `project.json` settings. For each source string which has translation in loctool (i.e. provided via loctool's xliff files), this translation will optionally be unescaped as described above and will be insterted into the corresponting `\u003ctarget\u003e` element content in the output file.\n\nAdditionally, this plugin supports output locale mapping.\n\n## Example localization process\n\nBelow you can find a step-by-step process to showcase the plugin's intention.\n\nGiven a source Pendo XLIFF file `$PROJECT/guides/A000A00Aaa0aaa-AaaaAaa00A0a_en.xliff`\n\n```xml\n\u003cxliff version=\"1.2\" xmlns=\"urn:oasis:names:tc:xliff:document:1.2\"\u003e\n    \u003cfile original=\"A000A00Aaa0aaa-AaaaAaa00A0a\" datatype=\"pendoguide\" source-language=\"en-US\" target-language=\"\"\u003e\n        \u003cbody\u003e\n            \u003cgroup id=\"Aaaaaaaa0aAaaAAA0AAA0A0aAaa\"\u003e\n                \u003ctrans-unit id=\"8de49842-c1fd-4536-905e-8817673b4c24|md\"\u003e\n                    \u003csource\u003e\u003c![CDATA[**Callout!**]]\u003e\u003c/source\u003e\n                    \u003ctarget\u003e\u003c/target\u003e\n                    \u003cnote\u003eTextView\u003c/note\u003e\n                \u003c/trans-unit\u003e\n            \u003c/group\u003e\n        \u003c/body\u003e\n    \u003c/file\u003e\n\u003c/xliff\u003e\n```\n\nand the following loctool configuration\n\n```json\n{\n    \"name\": \"ilib-loctool-pendo-md-test\",\n    \"id\": \"ilib-loctool-pendo-md-test\",\n    \"description\": \"translate strings exported from Pendo\",\n    \"projectType\": \"custom\",\n    \"sourceLocale\": \"en\",\n    \"includes\": [\"guides/*.xliff\"],\n    \"settings\": {\n        \"xliffsDir\": \"translations\",\n        \"locales\": [\"pl-PL\"],\n        \"localeMap\": {\n            \"pl-PL\": \"pl\"\n        },\n        \"pendo\": {\n            \"mappings\": {\n                \"guides/*.xliff\": {\n                    \"template\": \"[dir]/[basename]_[locale].[extension]\"\n                }\n            }\n        }\n    },\n    \"plugins\": [\"ilib-loctool-pendo-md\"]\n}\n```\n\ninvoking\n\n```sh\nloctool localize \"$PROJECT\"\n```\n\nwill first run the _extract_ step and produce a loctool XLIFF with extracted **escaped** strings `$PROJECT/ilib-loctool-pendo-md-test-extracted.xliff`:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\n\u003cxliff version=\"1.2\"\u003e\n  \u003cfile original=\"\" source-language=\"en\" product-name=\"ilib-loctool-pendo-md-test\"\u003e\n    \u003cbody\u003e\n      \u003ctrans-unit id=\"1\" resname=\"8de49842-c1fd-4536-905e-8817673b4c24|md\" restype=\"string\" datatype=\"plaintext\"\u003e\n        \u003csource\u003e\u0026lt;c0\u0026gt;Callout!\u0026lt;/c0\u0026gt;\u003c/source\u003e\n        \u003cnote\u003eTextView [c0: strong]\u003c/note\u003e\n      \u003c/trans-unit\u003e\n    \u003c/body\u003e\n  \u003c/file\u003e\n\u003c/xliff\u003e\n```\n\nnotice that:\n\n1. markdown strong `** **` in the source string is now escaped as components `\u003cc0\u003e \u003c/c0\u003e`\n2. trans-unit comment is updated to include description of the escaped components: _[c0: strong]_\n\nThen, loctool will immediately run the _localize_ step and produce a (not really) localized copy of the source file `$PROJECT/guides/A000A00Aaa0aaa-AaaaAaa00A0a_en_pl.xliff`:\n\n```xml\n\u003cxliff version=\"1.2\" xmlns=\"urn:oasis:names:tc:xliff:document:1.2\"\u003e\n    \u003cfile original=\"A000A00Aaa0aaa-AaaaAaa00A0a\" datatype=\"pendoguide\" source-language=\"en-US\" target-language=\"pl\"\u003e\n        \u003cbody\u003e\n            \u003cgroup id=\"Aaaaaaaa0aAaaAAA0AAA0A0aAaa\"\u003e\n                \u003ctrans-unit id=\"8de49842-c1fd-4536-905e-8817673b4c24|md\"\u003e\n                    \u003csource\u003e\u003c![CDATA[**Callout!**]]\u003e\u003c/source\u003e\n                    \u003ctarget/\u003e\n                    \u003cnote\u003eTextView\u003c/note\u003e\n                \u003c/trans-unit\u003e\n            \u003c/group\u003e\n        \u003c/body\u003e\n    \u003c/file\u003e\n\u003c/xliff\u003e\n```\n\nnotice that:\n\n1. target tag stays empty because there is no translation available yet\n2. file name includes mapped output locale `pl` rather than the translation locale `pl-PL`\n3. `target-language` attribute is also filled using the mapped output locale\n\nNow you need to obtain translations. Assume you've sent the loctool XLIFF file `$PROJECT/ilib-loctool-pendo-md-test-extracted.xliff` to a linguist and received translations for locale `pl-PL`. Following your project's config, you put it in `$PROJECT/translations/ilib-loctool-pendo-md-test-pl-PL.xliff`:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\n\u003cxliff version=\"1.2\"\u003e\n  \u003cfile original=\"\" source-language=\"en\" target-language=\"pl-PL\" product-name=\"ilib-loctool-pendo-md-test\"\u003e\n    \u003cbody\u003e\n      \u003ctrans-unit id=\"1\" resname=\"8de49842-c1fd-4536-905e-8817673b4c24|md\" restype=\"string\" datatype=\"plaintext\"\u003e\n        \u003csource\u003e\u0026lt;c0\u0026gt;Callout!\u0026lt;/c0\u0026gt;\u003c/source\u003e\n        \u003ctarget\u003e\u0026lt;c0\u0026gt;Wywołanie!\u0026lt;/c0\u0026gt;\u003c/target\u003e\n        \u003cnote\u003eTextView [c0: strong]\u003c/note\u003e\n      \u003c/trans-unit\u003e\n    \u003c/body\u003e\n  \u003c/file\u003e\n\u003c/xliff\u003e\n```\n\nnote that the target also has `\u003cc0\u003e \u003c/c0\u003e` tags in it, since your linguist knew how to handle XML-like tags properly.\n\nRunning loctool again\n\n```sh\nloctool localize \"$PROJECT\"\n```\n\nthis time, it will load the _pl-PL_ translations from the file specified in your `xliffsDir` folder and _localize_ step will backconvert and insert those translations while regenerating the (now actually) localized file `$PROJECT/guides/A000A00Aaa0aaa-AaaaAaa00A0a_en_pl.xliff`:\n\n```xml\n\u003cxliff version=\"1.2\" xmlns=\"urn:oasis:names:tc:xliff:document:1.2\"\u003e\n    \u003cfile original=\"A000A00Aaa0aaa-AaaaAaa00A0a\" datatype=\"pendoguide\" source-language=\"en-US\" target-language=\"pl\"\u003e\n        \u003cbody\u003e\n            \u003cgroup id=\"Aaaaaaaa0aAaaAAA0AAA0A0aAaa\"\u003e\n                \u003ctrans-unit id=\"8de49842-c1fd-4536-905e-8817673b4c24|md\"\u003e\n                    \u003csource\u003e\u003c![CDATA[**Callout!**]]\u003e\u003c/source\u003e\n                    \u003ctarget state=\"translated\"\u003e**Wywołanie!**\u003c/target\u003e\n                    \u003cnote\u003eTextView\u003c/note\u003e\n                \u003c/trans-unit\u003e\n            \u003c/group\u003e\n        \u003c/body\u003e\n    \u003c/file\u003e\n\u003c/xliff\u003e\n```\n\nwhich you can safely import back to Pendo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-loctool-pendo-md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filib-js%2Filib-loctool-pendo-md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-loctool-pendo-md/lists"}