Repository: cordova-docs Updated Branches: refs/heads/master 9b43362c4 -> 90c5831df
move translation parts of README/en/README.md to new translate.md Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/e6a7ad5e Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/e6a7ad5e Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/e6a7ad5e Branch: refs/heads/master Commit: e6a7ad5e9ab1c309de506b22ba0f87d9892f1bc6 Parents: 9b43362 Author: Jan Piotrowski <[email protected]> Authored: Tue Sep 26 16:22:48 2017 +0200 Committer: Jan Piotrowski <[email protected]> Committed: Tue Sep 26 16:22:48 2017 +0200 ---------------------------------------------------------------------- doc/README/en/README.md | 147 +---------------------------------------- doc/translate.md | 154 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+), 145 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/e6a7ad5e/doc/README/en/README.md ---------------------------------------------------------------------- diff --git a/doc/README/en/README.md b/doc/README/en/README.md index c45fc0e..d2db879 100644 --- a/doc/README/en/README.md +++ b/doc/README/en/README.md @@ -43,20 +43,6 @@ Pull requests are welcome! We appreciate the use of topic branches. # send pull request from branch issue_23 to cordova:master -### Adding a Language - -Do you want the Apache Cordova documentation in another language? We do too! With the support of [Crowdin](http://crowdin.net/project/cordova), a translation and localization management platform, translators can login to the easy-to-use tooling and provide as much or as little translation assistance as they would like. If you know another language please support Cordova and contribute. http://crowdin.net/project/cordova. For some best practices for using the Crowdin tool please see our wiki http://wiki.apache.org/cordova/CordovaTranslations. - -Cordova language administrators, don't forget these steps: - -__1. config.json__ - -For each language and version, there is a `config.json` that defines the name of the language and how to merge the files. - -__2. Customizing HTML template__ - -Each language can override the default template in `template/docs/LANGUAGE`. - ### Editorial Guidelines Please see the `STYLEGUIDE.md` file for guidelines on language and usage. @@ -112,142 +98,13 @@ or manually, to the script, as follows: node ./tools/bin/incrementversion.js www/docs X.X.X YY -QA for docs & translation +QA for docs ------------------------- 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 dev # 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. +1. `validatejsdoc` tool. ### 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. - * on Linux: - - cp tmp/ru/cordova-docs/docs/ru/dev/* docs/ru/dev/ - - * on Windows: - - xcopy tmp/ru/cordova-docs/docs/ru/dev/* docs/ru/dev/ - -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 dev - -7. Run generator. You should generate both English version and language which you tranlate. - - bin/genjs en dev - bin/genjs ru dev - - The generated documentation contains in the `public/en/dev` and `public/ru/dev` - - You need both versions, to validate that translated docs would have same structure as original documentation. - -8. Validate you translation. - - bin/translationreport ru dev - - This will give you list of files which has structural differences from the original docs. - Below the example output: - - => Validating translation for version dev on language ru... - Comparing C:\Users\kant\Documents\GitHub\cordova-docs\public\en\dev - with C:\Users\kant\Documents\GitHub\cordova-docs\public\ru\dev - 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 dev -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 `cordova-docs` repository. - -Enjoy translation!!! http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/e6a7ad5e/doc/translate.md ---------------------------------------------------------------------- diff --git a/doc/translate.md b/doc/translate.md new file mode 100644 index 0000000..12ebb2a --- /dev/null +++ b/doc/translate.md @@ -0,0 +1,154 @@ +# Translate + +## Adding a Language + +(migrated from [README/en/README.md](README/en/README.md)) + +Do you want the Apache Cordova documentation in another language? We do too! With the support of [Crowdin](http://crowdin.net/project/cordova), a translation and localization management platform, translators can login to the easy-to-use tooling and provide as much or as little translation assistance as they would like. If you know another language please support Cordova and contribute. http://crowdin.net/project/cordova. For some best practices for using the Crowdin tool please see our wiki http://wiki.apache.org/cordova/CordovaTranslations. + +Cordova language administrators, don't forget these steps: + +__1. config.json__ + +For each language and version, there is a `config.json` that defines the name of the language and how to merge the files. + +__2. Customizing HTML template__ + +Each language can override the default template in `template/docs/LANGUAGE`. + +## QA for translation + +(migrated from [README/en/README.md](README/en/README.md)) + +In order to maintain quality of documentation and translation, following tools could be used. + +1. `fixyaml` tool. +2. `translationreport` 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 dev # 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. + +## Recommendations for the translators + +(migrated from [README/en/README.md](README/en/README.md)) + +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. + * on Linux: + + cp tmp/ru/cordova-docs/docs/ru/dev/* docs/ru/dev/ + + * on Windows: + + xcopy tmp/ru/cordova-docs/docs/ru/dev/* docs/ru/dev/ + +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 dev + +7. Run generator. You should generate both English version and language which you tranlate. + + bin/genjs en dev + bin/genjs ru dev + + The generated documentation contains in the `public/en/dev` and `public/ru/dev` + + You need both versions, to validate that translated docs would have same structure as original documentation. + +8. Validate you translation. + + bin/translationreport ru dev + + This will give you list of files which has structural differences from the original docs. + Below the example output: + + => Validating translation for version dev on language ru... + Comparing C:\Users\kant\Documents\GitHub\cordova-docs\public\en\dev + with C:\Users\kant\Documents\GitHub\cordova-docs\public\ru\dev + 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 dev -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 `cordova-docs` repository. + +Enjoy translation!!! \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
