Create a mechanism to create translatable, themable diagrams

[robredpath]

• Minimum requirement is guidance for @kd-ods to start writing docs (eg recommended SVG tool or the informed belief that we can use Mermaid (or similar)) even if we need to do more work to make it pretty

• Doing the work of prettification is out of scope, as long as it's <10days work to do such prettification

[timgdavies]

Rough example of the kind of document.

[Bjwebb]

I think it would be a lot of work to make mermaid.js create something that looks sufficiently like the example diagram. (Mermaid has "themes" but they're basic colour switching, I think we'd end up writing a lot of our own drawing code.) Additionally I think we'd have to translate the entire mermaid document for an object in one go.

By contrast, we can translate each piece of text in SVGs seperately (and push to transifex etc.). I've had good success using http://itstool.org/ and and this example its-rules.xml.

Using a random image off wikimedia, and a pseudo translation:

itstool -i its-rules.xml -o Motherboard_diagram.po Motherboard_diagram.svg
podebug --rewrite unicode Motherboard_diagram.po > Motherboard_diagram_pesudo.po
msgfmt Motherboard_diagram_pesudo.po
itstool -m messages.mo -o Motherboard_diagram_translated.svg Motherboard_diagram.svg

This example image was created using inkscape. I've also created inkscape svgs from scratch that work well also.

Is "use inkscape" useful advice?
What's the source of the example diagram? Would it be useful to demo translating that?

[kd-ods]

I think 'use inkscape' is probably realistic in the short-term. I could create a library of objects, that we can re-use to create the diagrams.

What would have happened in your hardware diagram, Ben, had any of the within-object strings been much longer in translation than in the base language?

(Also, just want to record on this thread an interesting code-and-direct-manipulation SVG tool that Jack mentioned: Sketch-n-Sketch. It's probably not stable enough to use at the moment, but maybe useful for the future.)

[Bjwebb]

What would have happened in your hardware diagram, Ben, had any of the within-object strings been much longer in translation than in the base language?

Good question. It will expand in a direction depending on how the text is aligned (if text is right aligned it will extend to the left, and vice versa). It's also possible to do multiline wrapped text with inkscape, which will extend downwards.

[Bjwebb]

BTW, I took a look at Google Drawings, which will export a SVG, but one that contains paths for the text, instead of the text itself. This could be useful for exporting the rest of the diagram though, and then the text would need recreating.

Here's a script that will fake translate a svg file by putting "xxx" at the start and end of each string -
https://gist.github.com/Bjwebb/030e0bf13c0ec56b725beafac477bde4. Hopefully gives an idea of what will happen for longer translations.

How to use:

wget https://gist.githubusercontent.com/Bjwebb/030e0bf13c0ec56b725beafac477bde4/raw/b11b9a86ff0f1474a315db97c58f54ff137ad6a4/its-rules.xml
wget https://gist.githubusercontent.com/Bjwebb/030e0bf13c0ec56b725beafac477bde4/raw/057a169bfebd523510aebc6ef8be083f1b633558/translate.sh
sudo apt install itstool
./translate.sh name_of_file.svg

Then open name_of_file_translated.svg in inkscape .

[kd-ods]

Thanks, Ben! I exported a diagram from Google Draw to SVG and re-added some of the text 'properly' in Inkscape (to produce this SVG) so that I could use your scripts. The scripts seem to run OK but the text in the new SVG file wasn't translated. Maybe something to do with the export from Google Draw and XML format? Or the XXXs not being added in the PO file? Not sure. I'll look into it when I have a minute.

[Bjwebb]

Looks like I'd typo'd in translate.sh but some translations were persisting from previous commands I'd run.
Here's an updated translate.sh which should work for that svg.

[kd-ods]

Got it - that works great. Thanks, Ben!

[kd-ods]

Noting here that a more suitable alternative to Mermaid might be the "sketch-n-sketch":http://ravichugh.github.io/sketch-n-sketch/ system (currently under development). It allows SVG diagrams to be coded or created through direct manipulation and for constraints to be added as required. Worth keeping an eye on.