Publishing translated documentation                                                                         

Tuesday, November  5 •     3:40pm -  4:20pm
Design Summit 1
      
1. Current status

Translation status ( go to transifex: https://www.transifex.com/projects/p/openstack-manuals-i18n/ )
Document translations not following community process, e.g. CloudWatt, a French company, has translated 400 pages.
Japanese website page is not merged into doc website repository: http://openstack-ja.github.io/openstack-manuals/ja/

Tool status:
manuals-upstream-translation-update (triggered by update): works only under openstack-manuals
manuals-propose-translation-update (periodic): doesn't work
	error msg: https://jenkins.openstack.org/job/manuals-propose-translation-update/193/console
openstack-operations-guide-ja: not built
	https://git.openstack.org/cgit/openstack-infra/config/tree/modules/openstack_project/files/jenkins_job_builder/config/manuals.yaml
	demerits: specific to "ja" (not acceptable, should be templatized for 2-letter language code), specific to "openstack/operations-guide" (acceptable to have separate repos)

2. Publish process

publish when ready (high quality, translators preferred) V.S. continous publish (see results as soon as possible)
Define a publish job:  to generate HTML and publish, similar as openstack-operations-guide-ja

Choice 1: publish when ready
Suitable situation: (1)publish the translated documents only when it is completed after review. (2) seldom English document changes
Process: 
a>when the translation is ongoing->  manuals-propose-translation-update(periodic)->coordinators review and agree to merge -> translation completed -> publish job(manually triggered by coordinators)

b>  translation update after publish->manuals-propose-translation-update(periodic)->coordinators review and agree to merge->publish job(manually triggered by coordinators)

c> when English documents change ->manuals-upstream-translation-update->translation change->manuals-propose-translation-update(periodic)->coordinators review and agree to merge->publish job(manually triggered by coordinators)

Need to take into consideration: the workload of coordinators
so, maybe a weekly review. 

Use tag event to trigger the publish job.

Choice 2: Continous publish
Suitable situation: (1) continously publish the translated documents while they are under construction
Process: 
a>  translation ongoing->   manuals-propose-translation-update(periodic)->coordinators review and  agree to merge -> publish job(triggered by po file changes)

b>   translation update->manuals-propose-translation-update(periodic)->coordinators  review and agree to merge->publish job(triggered by po file changes)

c>  when the English documents change  ->manuals-upstream-translation-update->translation  change->manuals-propose-translation-update(periodic)->coordinators  review and agree to merge->(triggered by po file changes)

Can we select both ?
	* a offical server to host the good quality translated documents (high priority)
	* a staging server to host the ongoing translated documents. <-- helpful for the review process

what need to be done:
	* merge Japanese website HTML page to doc website repository with the URL: http://docs.openstack.org/ops/ja
		* more details: to which folder? \openstack-manuals\www Anne todo with the links identical to  http://openstack-ja.github.io/openstack-manuals/ja/ with a dropdown for selecting another language (extra bonus! Get javascript from Stephen Gordon for some sort of auto-detect preferred first language presented by browser) https://review.openstack.org/55227 without extra bonus
	* manuals-upstream-translation-update & manuals-propose-translation-update: make them runnable under openstack/openstack-ops
	* improve the publish job
		* make it runnable successfully for japanese & french operation guide
		* make more generic, e.g. use the language as a parameter, use the document as a parameter
		* use the same script to support both manually triggered job (to update the offical doc server) and event triggered job (to update the staging doc server)

3. Questions to be discussed: 
    
Q: Where does the slicing tool live?
A:
	* ITS tools embedded with translation tools may be a solution
	* But for now, the alternative solution is ...
	* decision: let's get a doctools repository, ITS could live there, as could gate tests, automation of all the things

Option 1: as a plugin to each doc projects, downloaded when required, similiar as oslo
( Need help of a people who understand this machinism )
Option 2: put it to every doc projects.
Option 3: ?  

Q: Is it a way for translation team to review the documents (even not finished), add comments and reply?
A: staging server, add comments to translated documents
(leveraging the current doc experiences in comments and replies)
<-- doc comment --> 
(Advanced requirement. Now no good ways to support)

Q: How to handle the translated documents which are managed by translation tools?
A: upload PDF directly? provide links in the openstack official doc website ?
Change those translations into po and upload to Transifex. It's good to leverage translation memory.

Q: Is it worth having semi-translated documents available online
A: Yes, it can gain more awareness of translation community

Q: Do we do automated language detection?
A: Maybe