Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (athena.apache.org: domain of kant2002@googlemail.com
 designates 209.85.223.170 as permitted sender)
MIME-Version: 1.0
Date: Thu, 25 Dec 2014 00:41:22 +0600
Message-ID: 
 <CAAY=exh9QGgmJLvPgfU6r7JXU-yKjziVL52FKGL6ptsMec1_Lg@mail.gmail.com>
Subject: Thought on improving translation and docs
From: Andrey Kurdumov <kant2002@googlemail.com>
To: dev@cordova.apache.org
Content-Type: multipart/alternative; boundary=047d7bdc117e58fad3050afaa34b

--047d7bdc117e58fad3050afaa34b
Content-Type: text/plain; charset=UTF-8

Once I finish moving documentation generation to JS I now have plans how to
move forward with improving translation.

First thing to finish is to cleanup task which was left after migration
These which was mentioned by Andrew:
- update the README.md to describe how to generate using the new generator
- delete the ruby files!
- Change path for generation from public/test/ to public/

Next is the improve quality of translation. Right now autolinking in
translated languages almost is broken. You could compare [1] and [2] or [3]
to understand what I mean. That's when you change header of the page, you
should go across all pages where this term is used and change reference to
that page everywhere. That's almost impossible to do without tooling
support. So I decide to create tool(s) which will help keep consistency.

Here I will use Russian as a second language which I will translate.

Tool 1: Translation comparator
I compare how many links I have in English translation with links which I
have in Russian traslation and generate report of differences.
This tool could give overview of translation quality for language.

Example usage:
./bin/translationreport ru edge

Example output:
Comparing translation for en and ru for version edge
Comparing index.md .... OK
Comparing guide/platforms/index.md .... Found differences

Tool 2. Find autolinks
This tool will report which part of Markdown file will be used in the
autolinking feature. That's to know what text should you use during
translation in the other parts.
Example usage:
./bin/findautolinks en/edge/config_ref/images.md

Example output:
Found terms:
Icons and Splash Screens
Example configuration
Supported platforms
Splashscreen Plugin

Tool 3. Find linked pages
When given Markdown file name, then this tool will report from which other
Markdown files this file is referenced.
Example usage:
./bin/findrefautolinks en/edge/guide/cli/index.md

Example output:
Searching for autolinks
Found:
guide/platforms/index.md
config_ref/images.md
.......


Alternative way is to move away from autolinking completely and provide
another tool

Tool 4.
Replace places in existing MD files where autolinking happens with direct
links
Example usage
./bin/replaceautolinks en edge

Example output:
Performed replace

That's just my ideas how translation could be improved. I just want to
bring this to discussion, to have broader view on the topic before start
doing something.
Also I have question about CrowdIn - I want to intensively check what how
my translation in Crowdin broke the autolinking. Is is possible  have
readonly API keys which allows me doing translation in CrowdIn, and
generate documentation locally, to check that changes in wording, don't
break autolinking?

[1] http://cordova.apache.org/docs/en/edge/index.html
[2] http://cordova.apache.org/docs/ru/edge/index.html
[3] http://cordova.apache.org/docs/es/edge/index.html

Thanks,
Andrey

--047d7bdc117e58fad3050afaa34b--