Andrey~ The information on the translation process is available on our wiki here: http://wiki.apache.org/cordova/CordovaTranslations. It'd be nice if we had additional information somewhere to get people's attention before they start translating. I'm open to suggestions on where to put the details. The crowdin site doesn't allow me to have a "readme" type of file.
The reason the links as broken (as talked about in the wiki) is because the translations do not match between the headers on different pages. For example, one might say "hi" and the other says "hello". They mean the same thing but because the characters aren't EXACT, the link is broken. When they appear black that is the cause. It's a very manual and frustrating process to have to go and compare the broken link translations and make sure they match for each language and every link. I believe this is just a shortcoming of using markdown. We could probably put in a bunch of hardcoded links but that'll take some work on our part to get the docs all setup. It's a good suggestion though, I'm all for making it easier on translators/me. Lisa Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | [email protected] | | [email protected] | lisaseacat.com | | From: Andrey Kurdumov <[email protected]> To: [email protected] Date: 05/26/2014 05:01 AM Subject: Documentation generation process Hi guys, I start verifying how my translation to Russian look at the actual site and found that sometimes links does not displayed on the same place where they are in English docs. Initially I start from http://cordova.apache.org/docs/ru/edge/guide_platforms_index.md.html where almost all links are broken. I check Italian and French translation, almost all link are in place, so I made assumption that this is probably something wrong with my translation and go to the Github to look at actual .md files. https://raw.githubusercontent.com/apache/cordova-docs/master/docs/en/3.4.0/guide/platforms/index.md https://raw.githubusercontent.com/apache/cordova-docs/master/docs/ru/3.4.0/guide/platforms/index.md I find that no actual links are in the Markdown files. So I assume that some magic in generator is injecting links. I start looking at the cordova-docs/lib folder and don't find anything. I look and joDoc and find that there some function which look across all H1 in all files and use that H1 as link targets in the docs. This is raises following questions in my head: 1. Does I correctly find root cause for broken links in the docs? Could somebody with more knowledge about docs generation confirm that and give more details about how this working, because I may miss some other things. 2. Could we put information for translators how links are generated. That way they will know that all references to other sections should be in the same grammatical case as name of the section. That should be strict rule for transaltors, since it could make content orphaned. Also not technical translators could fix such issue themselves. 3. Could we put cordova-docs/CONTRIBUTING.md in the docs foder, so it could be translated for other languages. Also that file could be separated on stylistical rules, which probably would be universal across all languages, and language specific grammar rules and common grammar/orthographical mistakes which people made. There are more broader question: 4. Do the need such simple system for linking, which could be easily broken when we have 2 files with same H1 content For example would be not uncommon to have sections like 'Overview', 'Upgrading' and so on to appear in multiple areas, like in multiple plugins. For example: http://cordova.apache.org/docs/en/edge/guide_platforms_ios_config.md.htmland this was recorded as CB-5464 (as of 3.1 release).
