cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [2/3] docs commit: Add the documentation explaining how to use translation tools
Date Mon, 15 Jun 2015 18:48:21 GMT
Add the documentation explaining how to use translation tools


Branch: refs/heads/master
Commit: 6d1bb8ac4a0c37670825788edab729d8ee59fdde
Parents: 45d1034
Author: Andrey Kurdyumov <>
Authored: Sun May 17 03:30:41 2015 +0600
Committer: Andrey Kurdyumov <>
Committed: Sat Jun 13 14:10:34 2015 +0600

---------------------------------------------------------------------- | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)
diff --git a/ b/
index e12e7e3..ec25588 100644
--- a/
+++ b/
@@ -116,3 +116,144 @@ There is a Rake task to increment the version, generate the version
directory, a
     # generate version 4.1.0 for english.
     .\bin\incrementversion en 4.1.0
+QA for docs & translation
+In order to maintain quality of documentation and translation, following tools could be used.
+1. `fixyaml` tool.
+2. `translationreport` tool.
+3. `validatejsdoc` tool.
+### FixYaml tool.
+The tool `fixyaml` created to automatically fix YAML headers in the translation files after
+exporting translated content from CrowdIn. Sometimes Crowdin messup with Apache license headers

+and this tool created to fix that.
+    bin\fixyaml             # Runs fixyaml across all docs.
+    bin\fixyaml ru          # Runs fixyaml across all Russian docs.
+    bin\fixyaml ru edge     # Runs fixyaml on the latest Russian docs.
+    bin\fixyaml ru 5.0.0    # Runs fixyaml on the version 5.0.0 of Russian docs.
+### Translation Report tool.
+The tool `translationreport` currently provide two QA checks for translation.
+1. It verifies that autolinking works after translation, and that translated text point to
the same pages as 
+in the original documentation.
+2. It verifies that translated and original files create same DOM structure, since after
exporting from 
+Crowdin, the markdown files could contain unnescessary lines, which lead to broken HTML,
and could create 
+not needed code sections for example.
+### Validate JSDoc tool.
+The tool `validatejsdoc` allow verification of the current implementation of JSDoc with reference
+It was used during porting JSDoc to the Node version of JSDoc, and now currently not used
in the workflow.
+Recommendations for the translators
+If you intend to create quality translation of the Cordova docs, please not only 
+work in Crowdin and translate documentation, but also please go extra mile and verify that
+generated documentation for your language is also produce quality results.
+For that you should have Crowdin CLI tool. You could
+1. take it from [here]( 
+2. or install alternate NodeJS client
+    `npm -g install crowdin-cli`
+You will use that tool for the downloading translation from Crowdin. 
+To be able to download translated content from the Crowdin you should have API key for the
+Please ask for it on the mailing list.
+After you receive access to API key, create `crowdin.yaml` coniguration file, as described
in the [CrowdIn cli tool page](
+Now you ready to download content from CrowdIn.
+Run following commands (All commands here would be for NodeJS version of Crowdin CLI)
+1. Prepare translated content for downloading.
+   `crowdin-cli export`
+   This command collect latest translations and made them available for downloading. Without
that command, the translation which you would download would be stalled.
+   Be careful with this command, since Crowdin implement throttling and allow you export
content not faster then 1 time in 30 minutes, or so.
+2. Download content for you language. I will use Russian as example.
+   `crowdin-cli download -l ru -o`
+   This command download all translations for Russian language to the `` file.
+3. Now unpack the download content to the temporary directory.
+   `unzip -x -d tmp/ru`
+4. Copy the unpacked content to the `docs` folder.
+   a) on Linux: 
+    `cp tmp/ru/cordova-docs/docs/ru/edge/* docs/ru/edge/`
+   b) on Windows:
+    `xcopy tmp/ru/cordova-docs/docs/ru/edge/* docs/ru/edge/`
+5. Remove temporary directory. In my case `tmp/ru`.
+   Now you have fresh translation and could generate content.
+6. Fix Yaml headers by running.
+   `bin/fixyaml ru edge`
+7. Run generator. You should generate both English version and language which you tranlate.
+   ```
+   bin/genjs en edge
+   bin/genjs ru edge
+   ```
+   The generated documentation contains in the `public/en/edge` and `public/ru/edge`
+   You need both versions, to validate that translated docs would have same structure as
original documentation.
+8. Validate you translation.
+   `bin/translationreport ru edge`
+   This will give you list of files which has structural differences from the original docs.
+   Below the example output:
+     => Validating translation for version edge on language ru...
+    Comparing C:\Users\kant\Documents\GitHub\cordova-docs\public\en\edge
+    with C:\Users\kant\Documents\GitHub\cordova-docs\public\ru\edge
+    Path is different.
+    Path is different.
+    Path is different.
+    Path is different.
+9. Now you could open pregenerated files and compare the English version with your translated
+    Open both versions and find out what's wrong.
+    If on the first sight you could not find the differences, you could add switch `-v` which
will increase verbosity of the tool.
+    For example: 
+    `bin/translationreport ru edge -v`
+10. Currently there two type of errors reported: 
+    a. Missing or additional links.
+    b. The broken HTML structure.
+11. Let's fix first type of errors - Missing/Additional links.
+    To fix these type of errors you have to make sure that text in your translation where
you want to have link,
+    match exactly the header in the translated document, otherwise auto-linking would not
+    You have to rephrase the sentences to fix that.
+12. Broken HTML DOM structure.
+    Most likely this type of errors caused by the additional lines created by Crowdin during
+    You have to manually spot these places and remove additional lines when needed and then
commit your changes to Git.
+    Most likely these erorrs reappear after next exprot from CrowdIn, so don't hunt for these
errors until release, or create 
+    tool which will fix these error after each export and use it.
+13. Now you ready to create pull request with documentation to the main `crodova-docs` repository.

+Enjoy translation!!!
\ No newline at end of file

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message