Re: [OpenStack-I18n] [OpenStack-docs] Summary of how I18n affects with doc-migration
[resending to the lists]
On Aug 1, 2017, at 10:55 AM, Doug Hellmann <doug@doughellmann.com> wrote:
Excerpts from Andreas Jaeger's message of 2017-08-01 08:57:09 +0200:
On 2017-07-31 22:46, Doug Hellmann wrote:
Excerpts from Ian Y. Choi's message of 2017-08-01 03:16:09 +0900:
[...] 2. Draft index page for translated documents was also removed
Previously, Docs team maintained draft documents for the master branch (which will be the stable branch after the official release and the document stables) on https://docs.openstack.org/draft/draft-index.html page. It also contained translated draft documents and I18n team accessed the page to see whether translated documents render well or not, and also review translated strings.
I did not notice when I saw the spec [1], but recently, I noticed that the the draft-index.html page was deprecated by [next-release-name]/index.haml (e.g., https://docs.openstack.org/pike/index.html ) [4].
Since I18n team encourages translation review for the better quality of translations, it is a good idea to see draft documents before language landing pages have the link to fully translated and reviewed documents.
Is it possible to see the draft of a translation by reviewing the output of the job that proposes the patch containing the translated text?
Currently not, it needs publishing to docs-draft and a way to access the multiple documents. Note this needs handling for both openstack-manuals and project repos like neutron (networking-guide).
Could we make it work that way? I understand why we need a separate review step for the translations, but not why we need a separate copy of the docs published outside of the context of a job in order to perform that review. (This is probably just me not understanding how a tool works.)
Motoki-san proposed an idea of translation status support using an yaml file in openstack-manuals [5], and I would like to discuss with I18n team how we deal with the change of draft index page.
How would that flag or information be used?
WE could just have the link to it added - dependent on the flag - to either: * language index * draft index
It seems like we want a list of languages for which there are translations for a given set of docs. We could use that to populate templates in a few different ways (link from the English version to the other languages, link from a $language landing page to all of the guides in that language, etc.).
I can advise someone on how to add those features, if we have a volunteer.
Doug
Hello, Doug Hellmann wrote on 8/2/2017 12:43 AM:
[resending to the lists]
On Aug 1, 2017, at 10:55 AM, Doug Hellmann <doug@doughellmann.com <mailto:doug@doughellmann.com>> wrote:
Excerpts from Andreas Jaeger's message of 2017-08-01 08:57:09 +0200:
On 2017-07-31 22:46, Doug Hellmann wrote:
Excerpts from Ian Y. Choi's message of 2017-08-01 03:16:09 +0900:
[...] 2. Draft index page for translated documents was also removed
Previously, Docs team maintained draft documents for the master branch (which will be the stable branch after the official release and the document stables) on https://docs.openstack.org/draft/draft-index.html page. It also contained translated draft documents and I18n team accessed the page to see whether translated documents render well or not, and also review translated strings.
I did not notice when I saw the spec [1], but recently, I noticed that the the draft-index.html page was deprecated by [next-release-name]/index.haml (e.g., https://docs.openstack.org/pike/index.html ) [4].
Since I18n team encourages translation review for the better quality of translations, it is a good idea to see draft documents before language landing pages have the link to fully translated and reviewed documents.
Is it possible to see the draft of a translation by reviewing the output of the job that proposes the patch containing the translated text?
Currently not, it needs publishing to docs-draft and a way to access the multiple documents. Note this needs handling for both openstack-manuals and project repos like neutron (networking-guide).
Could we make it work that way? I understand why we need a separate review step for the translations, but not why we need a separate copy of the docs published outside of the context of a job in order to perform that review. (This is probably just me not understanding how a tool works.)
It would be much nice if the job also supports the publication for translated documents, assuming that the translated document build work should not interfere with the main documentation build steps. But for general perspective, if the target of translation is not all of documents in openstack-manuals, we might need to analyze whether inclusion of translated document build jobs is better or not.
Motoki-san proposed an idea of translation status support using an yaml file in openstack-manuals [5], and I would like to discuss with I18n team how we deal with the change of draft index page.
How would that flag or information be used?
WE could just have the link to it added - dependent on the flag - to either: * language index * draft index
It seems like we want a list of languages for which there are translations for a given set of docs. We could use that to populate templates in a few different ways (link from the English version to the other languages, link from a $language landing page to all of the guides in that language, etc.).
I can advise someone on how to add those features, if we have a volunteer.
Doug
_______________________________________________ OpenStack-I18n mailing list OpenStack-I18n@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
On 2017-08-01 18:24, Ian Y. Choi wrote:
Hello,
Doug Hellmann wrote on 8/2/2017 12:43 AM:
[resending to the lists]
On Aug 1, 2017, at 10:55 AM, Doug Hellmann <doug@doughellmann.com <mailto:doug@doughellmann.com>> wrote:
Excerpts from Andreas Jaeger's message of 2017-08-01 08:57:09 +0200:
On 2017-07-31 22:46, Doug Hellmann wrote:
Excerpts from Ian Y. Choi's message of 2017-08-01 03:16:09 +0900:
[...] 2. Draft index page for translated documents was also removed
Previously, Docs team maintained draft documents for the master branch (which will be the stable branch after the official release and the document stables) on https://docs.openstack.org/draft/draft-index.html page. It also contained translated draft documents and I18n team accessed the page to see whether translated documents render well or not, and also review translated strings.
I did not notice when I saw the spec [1], but recently, I noticed that the the draft-index.html page was deprecated by [next-release-name]/index.haml (e.g., https://docs.openstack.org/pike/index.html ) [4].
Since I18n team encourages translation review for the better quality of translations, it is a good idea to see draft documents before language landing pages have the link to fully translated and reviewed documents.
Is it possible to see the draft of a translation by reviewing the output of the job that proposes the patch containing the translated text?
Currently not, it needs publishing to docs-draft and a way to access the multiple documents. Note this needs handling for both openstack-manuals and project repos like neutron (networking-guide).
Could we make it work that way? I understand why we need a separate review step for the translations, but not why we need a separate copy of the docs published outside of the context of a job in order to perform that review. (This is probably just me not understanding how a tool works.)
We publish as usual - the only difference is the addition of the link. Since we import translations without review, we want to give teams a chance to review a complete book before we link to it the first time. And thus, we built it and publish at the final URL - and only link from it from our drafts page. This is not done outside of a job. It's just that we didn't want to wait for each language team to review a manual, then make changes in translate.openstack.org, wait for next import, then another team blocking import etc - and thus never merging anything...
It would be much nice if the job also supports the publication for translated documents, assuming that the translated document build work should not interfere with the main documentation build steps.
But for general perspective, if the target of translation is not all of documents in openstack-manuals, we might need to analyze whether inclusion of translated document build jobs is better or not.
Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
On 2017-08-01 17:43, Doug Hellmann wrote:
[resending to the lists]
ah, answered privately - let me answer again ;)
On Aug 1, 2017, at 10:55 AM, Doug Hellmann <doug@doughellmann.com <mailto:doug@doughellmann.com>> wrote:
Excerpts from Andreas Jaeger's message of 2017-08-01 08:57:09 +0200:
On 2017-07-31 22:46, Doug Hellmann wrote:
Excerpts from Ian Y. Choi's message of 2017-08-01 03:16:09 +0900:
[...] 2. Draft index page for translated documents was also removed
Previously, Docs team maintained draft documents for the master branch (which will be the stable branch after the official release and the document stables) on https://docs.openstack.org/draft/draft-index.html page. It also contained translated draft documents and I18n team accessed the page to see whether translated documents render well or not, and also review translated strings.
I did not notice when I saw the spec [1], but recently, I noticed that the the draft-index.html page was deprecated by [next-release-name]/index.haml (e.g., https://docs.openstack.org/pike/index.html ) [4].
Since I18n team encourages translation review for the better quality of translations, it is a good idea to see draft documents before language landing pages have the link to fully translated and reviewed documents.
Is it possible to see the draft of a translation by reviewing the output of the job that proposes the patch containing the translated text?
Currently not, it needs publishing to docs-draft and a way to access the multiple documents. Note this needs handling for both openstack-manuals and project repos like neutron (networking-guide).
Could we make it work that way? I understand why we need a separate review step for the translations, but not why we need a separate copy of the docs published outside of the context of a job in order to perform that review. (This is probably just me not understanding how a tool works.)
Let's try https://review.openstack.org/489669
Motoki-san proposed an idea of translation status support using an yaml file in openstack-manuals [5], and I would like to discuss with I18n team how we deal with the change of draft index page.
How would that flag or information be used?
WE could just have the link to it added - dependent on the flag - to either: * language index * draft index
It seems like we want a list of languages for which there are translations for a given set of docs. We could use that to populate templates in a few different ways (link from the English version to the other languages, link from a $language landing page to all of the guides in that language, etc.).
doc-tools-check-languages.conf already contains this basically - as instructions on which manuals to build for which language. The "draft" is for versioned guides.
I can advise someone on how to add those features, if we have a volunteer.
I'm happy to comment as well, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
On 2017-08-01 19:06, Andreas Jaeger wrote:
On 2017-08-01 17:43, Doug Hellmann wrote:
[resending to the lists]
ah, answered privately - let me answer again ;)
On Aug 1, 2017, at 10:55 AM, Doug Hellmann <doug@doughellmann.com <mailto:doug@doughellmann.com>> wrote:
Excerpts from Andreas Jaeger's message of 2017-08-01 08:57:09 +0200:
On 2017-07-31 22:46, Doug Hellmann wrote:
Excerpts from Ian Y. Choi's message of 2017-08-01 03:16:09 +0900:
[...] 2. Draft index page for translated documents was also removed
Previously, Docs team maintained draft documents for the master branch (which will be the stable branch after the official release and the document stables) on https://docs.openstack.org/draft/draft-index.html page. It also contained translated draft documents and I18n team accessed the page to see whether translated documents render well or not, and also review translated strings.
I did not notice when I saw the spec [1], but recently, I noticed that the the draft-index.html page was deprecated by [next-release-name]/index.haml (e.g., https://docs.openstack.org/pike/index.html ) [4].
Since I18n team encourages translation review for the better quality of translations, it is a good idea to see draft documents before language landing pages have the link to fully translated and reviewed documents.
Is it possible to see the draft of a translation by reviewing the output of the job that proposes the patch containing the translated text?
Currently not, it needs publishing to docs-draft and a way to access the multiple documents. Note this needs handling for both openstack-manuals and project repos like neutron (networking-guide).
Could we make it work that way? I understand why we need a separate review step for the translations, but not why we need a separate copy of the docs published outside of the context of a job in order to perform that review. (This is probably just me not understanding how a tool works.)
Let's try https://review.openstack.org/489669
Working, see http://docs-draft.openstack.org/87/489887/1/check/gate-openstack-manuals-tox... Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
participants (3)
-
Andreas Jaeger
-
Doug Hellmann
-
Ian Y. Choi