https://github.com/ilib-js/ilib-loctool-pendo-md
https://github.com/ilib-js/ilib-loctool-pendo-md
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/ilib-js/ilib-loctool-pendo-md
- Owner: iLib-js
- License: apache-2.0
- Created: 2024-09-06T00:14:36.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-12T12:21:46.000Z (over 1 year ago)
- Last Synced: 2025-01-05T05:17:14.679Z (over 1 year ago)
- Language: TypeScript
- Size: 201 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
> :warning: **Deprecation Notice** :warning:
> This repository has been deprecated. Please use the corresponding package from the [iLib-js monorepo](https://github.com/iLib-js/ilib-mono) instead.
# ilib-loctool-pendo-md
[Loctool](https://github.com/iLib-js/loctool) plugin to handle translation strings exported from [Pendo](https://www.pendo.io/).
This plugin accepts an XLIFF file exported from Pendo (``) and extracts existing translation units from it mapping them 1:1 to loctool Resources with **escaped Markdown syntax**.
## Extraction
### Markdown Syntax
As 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:
```md
_italics_ or _italics_
**bold**
[links](example.com)
1. ordered lists
- unordered lists
* unordered lists
- unordered lists
```
And some custom extensions:
```md
~~Strikethrough~~
++Underline++
{color: #000000}colored text{/color}
```
There 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 ``.
### Escaping
Given a Pendo markdown string like
```markdown
String with _emphasis_, ++underline++, {color: #FF0000}colored text{/color} and [a link](https://example.com)
```
transform it to an escaped string
```text
String with emphasis, underline, color and a link
```
### Unescaping (backconversion)
After parsing a source string, plugin keeps track of escaped components:
```text
- c0: emphasis
- c1: underline
- c2: color #FF0000
- c3: link https://example.com
```
Thanks to that, during localization this plugin is able to **unescape** (backconvert) these components in a translated string:
```text
Translated string, translated link translated underline, translated emphasis translated color
```
it will transform it back to the markdown syntax
```markdown
Translated string, [translated link](example.com) ++translated underline++, _translated emphasis_ {color: $FF0000}translated color{/color}
```
Note that it supports shuffled order of components, since this is often required in different languages.
## Translation
During 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 `` element content in the output file.
Additionally, this plugin supports output locale mapping.
## Example localization process
Below you can find a step-by-step process to showcase the plugin's intention.
Given a source Pendo XLIFF file `$PROJECT/guides/A000A00Aaa0aaa-AaaaAaa00A0a_en.xliff`
```xml
TextView
```
and the following loctool configuration
```json
{
"name": "ilib-loctool-pendo-md-test",
"id": "ilib-loctool-pendo-md-test",
"description": "translate strings exported from Pendo",
"projectType": "custom",
"sourceLocale": "en",
"includes": ["guides/*.xliff"],
"settings": {
"xliffsDir": "translations",
"locales": ["pl-PL"],
"localeMap": {
"pl-PL": "pl"
},
"pendo": {
"mappings": {
"guides/*.xliff": {
"template": "[dir]/[basename]_[locale].[extension]"
}
}
}
},
"plugins": ["ilib-loctool-pendo-md"]
}
```
invoking
```sh
loctool localize "$PROJECT"
```
will first run the _extract_ step and produce a loctool XLIFF with extracted **escaped** strings `$PROJECT/ilib-loctool-pendo-md-test-extracted.xliff`:
```xml
<c0>Callout!</c0>
TextView [c0: strong]
```
notice that:
1. markdown strong `** **` in the source string is now escaped as components ` `
2. trans-unit comment is updated to include description of the escaped components: _[c0: strong]_
Then, 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`:
```xml
TextView
```
notice that:
1. target tag stays empty because there is no translation available yet
2. file name includes mapped output locale `pl` rather than the translation locale `pl-PL`
3. `target-language` attribute is also filled using the mapped output locale
Now 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`:
```xml
<c0>Callout!</c0>
<c0>Wywołanie!</c0>
TextView [c0: strong]
```
note that the target also has ` ` tags in it, since your linguist knew how to handle XML-like tags properly.
Running loctool again
```sh
loctool localize "$PROJECT"
```
this 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`:
```xml
**Wywołanie!**
TextView
```
which you can safely import back to Pendo.