Translating the documentation

PurplePlums commented 4 years ago

Expected behaviour

I would like to have the existing documentation integrated into Crowdin expansible for us to translate it into the used languages.

Actual behaviour

Please add it if possible

Steps to reproduce

Obviously it is not integrated in any CAT tool so far, and without one it would be hard to translate it.

Output from the debug section in the settings dialog

none

Expand

Relevant log output in the Log panel

Expand

pbek commented 4 years ago

Do you mean https://docs.qownnotes.org? The website is generated from markdown files from https://github.com/pbek/QOwnNotes/tree/develop/docs/content. It relies on readthedocs which is using mkdocs to generating the website. The markdown files can't be feeded into crowdin nor do I know a way to handle translations at all with readthedocs and mkdocs. 😬

PurplePlums commented 4 years ago

Trados is extremely flexible but we need to wait for the new version till 2021. https://www.sdltrados.com/products/trados-studio/free-trial.html

PurplePlums commented 4 years ago

In the meanwhile you may want to take a look on the software; I’m going to need a license anyway only Trados19 is not available atm

PurplePlums commented 4 years ago

Look whether this is working; Trados organizes and imports a huge variety of sources, and is the most popular CAT tool available. Also costly but there will be a free trial (assuming with the relevant features end of this year. In the meanwhile let’s extend the matter

pbek commented 4 years ago

nor do I know a way to handle translations at all with readthedocs and mkdocs.

👀

PurplePlums commented 4 years ago

What about source code translation? You’d need to only once prepare the code so that the translatable parts are highlighted. So far it’s not too much, if no CAT tool can handle it.

pbek commented 4 years ago

To my knowledge readthedocs and mkdocs can't handle translations, means there is no sane way to make https://docs.qownnotes.org multilingual.

PurplePlums commented 4 years ago

Hey hey why. Basically I did something similar once already to collect a bilingual text for training a Software.

All I think I need to do is making a single excel file with all the text, it’s still extendible and not much more work than going through a document for several languages from a CAT tool (this is why I seldom use CAT tools.)

So if it’s possible that different versions of the same matter be uploaded, the whole translation and the editing procedures will be applied easily.

Is it?

PurplePlums commented 4 years ago

A CAT tool like Smartling could do the most work and it would be easy to re-insert the translation into the source code, then there will be 60 more versions of the documentation - my question here is if THATs possible, I can arrange the translation.

For people who don’t speak languages it would definitely be helpful.

PurplePlums commented 4 years ago

https://www.deepl.com/en/docs-api/ Seems to cooperate with external sources, but also bringing on a link to the page(s) would do many a service, I assume.

pbek commented 4 years ago

Maybe we have a chance to get translated documentation. I'm currently working on recreating www.qownnotes.org with VuePress (static site generator with vue.js). I plan on integrating the documentation too there (there still is a loooot to do until I get there).

VuePress has support for multi-language: https://vuepress.vuejs.org/guide/i18n.html#site-level-i18n-config

PurplePlums commented 4 years ago

Sorry, that I don't understand where the link leads to and what's suggested there. In what way can I contribute a translation to the documentation, except copying the source code and rewriting the content in my languages?

pbek commented 4 years ago

I did not experiment with it yet. 😁

PurplePlums commented 4 years ago

OK the documentation looks awesome. Thank you for mentioning it. It’s like I said, it would be...

PurplePlums commented 4 years ago

Is it possible to start with something? :-) Thankyou!

pbek commented 4 years ago

I'm still torn apart in that regard. The only thing that I see is to translate every file in https://github.com/pbek/QOwnNotes/tree/develop/webpage/src directly. But there will no mechanism (like with crowdin) to tell that an English file was updated and needs new translation... so we would always generate misleading or obsolete documentation. 😢 Do you by chance know of a way to monitor all files in that folder?

PurplePlums commented 4 years ago

Here's the list of all cat tools: https://www.polilingua.com/blog/post/cat_tools.htm

PurplePlums commented 4 years ago

Those might solve the issue, Trados is very strong, has a free licence for one month. However possibly another software could take over.

pbek commented 4 years ago

It would have to be something that runs in the web, is free for free open source projects and somehow integrates into github and with the file-structure vuepress has for translations...

PurplePlums commented 4 years ago

Runs in the web for future tasks, but we’d provide human made translations.

Deep L would be a good resource.

PurplePlums commented 4 years ago

Can you give me an example, so I can search for a tool that handles it?

PurplePlums commented 4 years ago

Maybe just translate and update...

pbek commented 4 years ago

The example is:

All markdown files in https://github.com/pbek/QOwnNotes/tree/develop/webpage/src need to be monitored for changes.
If changes are found some web interface need to show those changes and translators need to be notified that changes occurred.

There basically will be a different directory tree for each translation. And it would be great if those were in-sync with the English version of the webpage.

That's not an easy thing to do. 😬

PurplePlums commented 4 years ago

Would you like me to translate text in order to have them available?

pbek commented 4 years ago

Of course that would be great, but my issue with translated documentation is https://github.com/pbek/QOwnNotes/issues/1859#issuecomment-717893293 😢

PurplePlums commented 4 years ago

Could content management systems be useful?

pbek commented 4 years ago

As long as the single source of truth are the files in https://github.com/pbek/QOwnNotes/tree/develop/webpage/src I don't care.

PurplePlums commented 4 years ago

Any preferences?

pbek commented 4 years ago

Anything that I don't need to maintain or pay for. 😆

PurplePlums commented 4 years ago

https://www.wachete.com/#pricing (no such freeware available)

https://www.comparitech.com/net-admin/file-activity-monitoring-tools/ (These are the others)

https://colorlib.com/wp/most-popular-content-management-systems/ (And finally it seems none of the CM systems do monitoring).

So far...

PurplePlums commented 4 years ago

There: https://en.freedownloadmanager.org/Mac-OS/File-Monitor.html

"From the developer:

File Monitor ... You need to be notified when files, folders or their contents are modified by someone? You want to monitor the content of particular folders or dropboxes? You want to monitor the modification of particular files? Then File Monitor is what you need! File Monitor allows you to be notified of modifications occurring to any kind of files. You can monitor several files and folders at the same time."

PurplePlums commented 4 years ago

While the latter seems to be testware, there are some more more or less freeware here: https://www.raymond.cc/blog/3-portable-tools-monitor-files-folders-changes/ but non of them are real freewares. Thus: nope, so far.

pbek commented 4 years ago

I think I need to first implement a German translation scaffolding (with the English content) to see how well it behaves with vuepress...

PurplePlums commented 4 years ago

Right. These are the three free CAT tools around: https://translatorthoughts.com/2016/08/top-three-free-cat-tools

PurplePlums commented 4 years ago

... let's see whether they are providing an update in some way.

PurplePlums commented 4 years ago

https://www.smartcat.com might be the solution. :-) ;-)

pbek commented 4 years ago

https://www.smartcat.com might be the solution. :-) ;-)

beside not being catered for FLOSS (you need to tell them you are a business) it could be a solution 👍🏻

pbek commented 4 years ago

I created an account and it seems there is a git integration (seems like you need to host that yourself) but the "documentation" https://github.com/smartcatai/smartcat-serge-sync-plugin doesn't even actually tell you how to use it...

pbek commented 4 years ago

I now added the necessary multi-site configuration and a copy of the English files in a new branch feature/german-webpage:

@PurplePlums, you could either work directly in https://github.com/pbek/QOwnNotes/tree/feature/german-webpage/webpage/src/de to edit all the "soon to be German" files or even better checkout the whole https://github.com/pbek/QOwnNotes git repository, switch to the feature/german-webpage branch and edit all files locally in webpage/src/de.

pbek commented 4 years ago

But without a way to keep the translations in sync all the effort will be soon in vain when the German webpage starts lagging behind and then may be outright incorrect and misleading...

PurplePlums commented 4 years ago

For updating pls see: https://help.smartcat.com/hc/en-us/articles/360029093171-Updating-a-Project https://help.smartcat.com/hc/en-us/articles/360001870691-Smartcat-integration-101-Basic-scenario-for-content-exchange

If this is not a suitable way to update QON documentation, maybe another CAT tool needs to be considered.

pbek commented 4 years ago

Uploading updated files that need translation and downloading translated files must be automatic or at least scriptable.

PurplePlums commented 4 years ago

None of the FLOSS CAT-tools does that.

Is it possible to create an up to date word file from the documentation upon user request? DeepL works with eleven languages and translates documents keeping their original format; and could be linked on each page. https://www.deepl.com/de/translator

pbek commented 4 years ago

Is it possible to create an up to date word file from the documentation upon user request?

What would be in that word-file (and why word?) and how does the data get back to 100+ markdown files? By a human? I could also write a GitHub workflow that could do something if a file in the webpage directory was changed.

pbek commented 4 years ago

Other question before I even bother with writing scripts... Are you already capable to translate the current documentation by any means mentioned in https://github.com/pbek/QOwnNotes/issues/1859#issuecomment-718963931?

PurplePlums commented 4 years ago

I want to figure it out, I can definitely do it, although it seems a lot this way as far as I understood it.

pbek commented 4 years ago

although it seems a lot this way as far as I understood it.

what do you mean? a lot to translate or a lot to figure out. do you need help with something?

PurplePlums commented 4 years ago

Do I use QON style for formatting?

PurplePlums commented 4 years ago

Well I don’t yet understand how to access the formatting so that I can either copy everything into MT and copy back, and how I format it then again as there is no way to format. Anyway, if I have to work from and produce source code, it will be a lot of work.

There it seems to me there’s no other way.

pbek commented 4 years ago

Do I use QON style for formatting?

you take the English markdown files in the de folder and replace the English text with German (where reasonable)

either copy everything into MT and copy back

if you copy the text somewhere else then it really needs to be plain text (markdown).

# I am a headline

I am a **bold text**.

Never convert the markdown to html and copy the the rich text from a html preview into MS Word or something, this way important information is lost.

I could write a script that gathers the content of all English files together and puts it into one, big markdown file if that would be of any help. But then you would need to copy and paste all the single file parts of the big files back into the German markdown files after translation every time. Was I able to make clear what I'm talking about?

pbek / QOwnNotes