Mailing-List: contact commits-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: steven@apache.org
To: commits@cordova.apache.org
Date: Mon, 15 Jun 2015 18:48:21 -0000
Message-Id: <5cbce98ee09144e8b3f2d15936024b94@git.apache.org>
In-Reply-To: <7b5a282947594ad1b743b4d6e0fce687@git.apache.org>
References: <7b5a282947594ad1b743b4d6e0fce687@git.apache.org>
Subject: [2/3] docs commit: Add the documentation explaining how to use
 translation tools

Add the documentation explaining how to use translation tools


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/6d1bb8ac
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/6d1bb8ac
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/6d1bb8ac

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

----------------------------------------------------------------------
 README.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/6d1bb8ac/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index e12e7e3..ec25588 100644
--- a/README.md
+++ b/README.md
@@ -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.
+
+Usage:
+
+    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 implementation.
+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](https://crowdin.com/page/cli-tool) 
+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 project.
+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](https://crowdin.com/page/cli-tool).
+
+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 ru.zip`
+   
+   This command download all translations for Russian language to the `ru.zip` file.
+   
+3. Now unpack the download content to the temporary directory.
+
+   `unzip -x ru.zip -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 guide_platforms_blackberry10_upgrade.md.html is different.
+    Path guide_platforms_blackberry_upgrade.md.html is different.
+    Path guide_platforms_ios_tools.md.html is different.
+    Path guide_support_index.md.html is different.
+```
+
+9. Now you could open pregenerated files and compare the English version with your translated versions.
+    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 work.
+    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 export.
+    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: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org