<html><body><p>Hello, team<br><br>There are three possible solutions to manage glossaries and their translations.<br>All of these solutions have their advantages and disadvantages.<br>I think we should prioritize the requirements firstly, then we make the choice based on the requirements.<br>Here I list some requirements.<br><br>#1. Save glossaries in i18n repo<br>#2. Translate and review with Zanata editor, and enable the auto sync between Zanata editor and i18n repo.<br>#3. View comments while translating<br>#4. Review the new added glossary by Gerrit<br>#5. View the list of glossaries and their comments in i18n documents.<br>#6. Keep the history of glossary translations and discussions.<br><br>Please let me know your thoughts to these requirements.<br>You can add comment "Must support", "good to have", and "not necessary" to each requirement,<br>and order these requirements by the priority in your mind.<br>If you have other requirements, feel free to add.<br><br>For your reference, here are the three possible solutions:<br><br>- Solution 1 Save glossaries in pot file and translations in po files.<br>The current solution in repo: openstack/i18n<br>Support requirement #1 , #2 and #4<br>( @Alex, please help to verify if #3 and #6 could be satisfied in this solution.)<br><br>- Solution 2 Save glossaries in rst file and translations in po files.<br><a href="https://review.openstack.org/#/c/258924/">https://review.openstack.org/#/c/258924/</a><br>Support requirement #1, #2, and #4, #5<br><br>- Solution 3 Save glossaries in YAML file and translations in YAML files.<br><a href="https://review.openstack.org/#/c/261767/">https://review.openstack.org/#/c/261767/</a><br><a href="https://review.openstack.org/#/c/262710/">https://review.openstack.org/#/c/262710/</a><br>Support requirement #1, #3 and #4, #6<br><br>Your input will help us to make a team decision.<br>Thank you.<br>Best regards<br>Ying Chun Guo (Daisy)<br><br><br><tt>Akihiro Motoki <amotoki@gmail.com> wrote on 2016/01/05 19:09:09:<br><br>> From: Akihiro Motoki <amotoki@gmail.com></tt><br><tt>> To: Ying Chun Guo/China/IBM@IBMCN</tt><br><tt>> Cc: "openstack-i18n@lists.openstack.org" <Openstack-i18n@lists.openstack.org></tt><br><tt>> Date: 2016/01/05 19:10</tt><br><tt>> Subject: Re: [Openstack-i18n] How do we manage glossary?</tt><br><tt>> <br>> 2016-01-05 18:00 GMT+09:00 Ying Chun Guo <guoyingc@cn.ibm.com>:<br>> > Thank you for the patch, Akihiro.<br>> > I think it's easier to discuss in email.<br>> > So I copied your comments in your patch here.<br>> ><br>> >> Expected workflow:<br>> >> * add an entry to the master glossary:<br>> >> - Update glossary/master.yaml and review it on gerrit<br>> >> - Once approved, glossary-tool sync will update per-language glossary<br>> >> files and propose the update to gerrit (jenkins jos)<br>> ><br>> > In your design, when the changes to master.yaml is approved, how to trigger<br>> > the jenkins job ? using a tag ?<br>> > I think we could add one more action in this Jenkins job: automatically send<br>> > an email to i18n to notify that the glossary is changed.<br>> <br>> We can use 'post' pipeline to trigger some jobs when each change is merged.<br>> <br>> >> * update per-language glossary:<br>> >> - Each language team upload a proposed glossary to gerrit. A language team<br>> >> members review it and once they have a consensus i18n core reviewer merges<br>> >> it into the repository.<br>> >> - Once approved, a corresponding glossary PO file is generated and<br>> >> uploaded to Zanata. (glossary-tool write-po and jenkins job)<br>> ><br>> > In your design, translators will not use translation editor in Zanata to<br>> > translate glossary.<br>> > Translators will propose the glossary translation to gerrit.<br>> > I don't know if translators have enough training to commit a patch.<br>> > They may understand how to use Zanata more than how to use gerrit.<br>> > There is no commands to support uploading glossary to Zanata.<br>> > So the action to upload po files have to be executed manually.<br>> <br>> I think uploading glossary can be done by Jenkins job triggered by<br>> 'post' job as well.<br>> I agree that translators are familiar with Zanata rather than Gerrit<br>> to some extent.<br>> <br>> However, my question is still how to keep discussion contexts (or<br>> history/background).<br>> It seems Zanata history is associated with Zanata internal resource ID.<br>> I am afraid it can be easily lost and we cannot recover it :-(<br>> <br>> > How do you think if we change to:<br>> > - Update glossary/master.yaml and review it on gerrit.<br>> > - Once approved, glossary-tool sync will update per-language glossary files<br>> > and propose the update to gerrit (jenkins jos).<br>> > - The jenkins job will upload pot file in Zanata.<br>> > - The jenkins job will send email to i18n to notify the change.<br>> > - Translators log in to Zanata to translate.<br>> > - Jenkins job download po files to i18n repository.<br>> > - Zanata admin automatic update Zanata glossary.<br>> <br>> Again, how can we maintain discussion contexts?<br>> <br>> On the other hand, I might be thinking "context" too much.<br>> If we go to the above way you mentioned,<br>> I think we need to maintain discussion contexts in other places.<br>> If the team suggests to do so, I am okay.<br>> <br>> Japanese team actually maintains it in OpenStack wiki and it works mostly well<br>> except that we need to sync glossary manually, but it might be a small thing<br>> compared to keep "context". Keeping "context" will save time to explain why<br>> we choose THIS in our current glossary. If we do not have it, we need to<br>> explain same things to new contributors again and again, and this <br>> will increase<br>> the barrier to new contributors.<br>> <br>> >> * syntax when a review is proposed<br>> >>- 'glossary-tool' check verifies if YAML data is valid. It can be a part of<br>> >> pep8 target.<br>> ><br>> > Good to have syntax check.<br>> ><br>> > BTW, how do you think the advantage of YAML file, comparing with po and pot<br>> > files?<br>> > Because if we use po and pot files directly, we could put "note" as comments<br>> > in pot files.<br>> > Do you want "note" also be translated ?<br>> <br>> The only reason is YAML file is human-friendly and easy to edit by <br>> text editors.<br>> I don't think it is a good idea to edit PO file directly.<br>> The format is not human-friendly and we can easily make mistakes in<br>> editing PO files.<br>> <br>> "note" in a PO file will be overridden if the glossary is downloaded<br>> from Zanata.<br>> This means we need to manage PO files directly in our git repo.<br>> I don't think maintaining PO files is more difficult than maintaining<br>> YAML files.<br>> <br>> <br>> Finally, I would like to purge ancient glossary on Zanata as soon aspossible.<br>> The current glossary harms translation and provides no value.<br>> <br>> Akihiro<br>> <br>> <br>> ><br>> > Regards<br>> > Daisy<br>> ><br>> ><br>> > Akihiro Motoki <amotoki@gmail.com> wrote on 2016/01/05 07:05:51:<br>> ><br>> >> From: Akihiro Motoki <amotoki@gmail.com><br>> >> To: Ying Chun Guo/China/IBM@IBMCN<br>> >> Cc: "openstack-i18n@lists.openstack.org"<br>> >> <Openstack-i18n@lists.openstack.org><br>> >> Date: 2016/01/05 07:07<br>> >> Subject: Re: [Openstack-i18n] How do we manage glossary?<br>> ><br>> >><br>> >> Hi Daisy and the team,<br>> >><br>> >> 2015-12-17 19:35 GMT+09:00 Ying Chun Guo <guoyingc@cn.ibm.com>:<br>> >> > Hi, Akihiro<br>> >> ><br>> >> > Please let me know your comments to <a href="https://review.openstack.org/258924">https://review.openstack.org/258924</a><br>> >><br>> >> I commented your above review.<br>> >><br>> >> I proposed a counter proposal <a href="https://review.openstack.org/261767">https://review.openstack.org/261767</a>.<br>> >> This is just an idea. I am open to the input.<br>> >><br>> >> Comments inline below.<br>> >><br>> >> > Answers to your question:<br>> >> ><br>> >> > 1. Context<br>> >> ><br>> >> > The current solution in my patch could not satisfy this requirement<br>> >> > about<br>> >> > context.<br>> >> > If we want to put context to glossary, we need to develop our own<br>> >> > extension<br>> >> > of sphinx-build.<br>> >> > How do you think the priority to support context ?<br>> >><br>> >> IMHO supporting contexts is important to make discussion on glossary<br>> >> productive.<br>> >> As you can see in Japanese glossary on OpenStack wiki [1], I believe<br>> >> that discussion contexts<br>> >> are important for further discussions and it also helps new<br>> >> contributors understand the background.<br>> >><br>> >> In my proposal <a href="https://review.openstack.org/261767">https://review.openstack.org/261767</a>,<br>> >> we maintain all contexts in YAML glossary files.<br>> >><br>> >> > 2. Process<br>> >> ><br>> >> > If people want to change the glossary, e.g. add, update, change the<br>> >> > comments, add coments<br>> >> > following process is designed.<br>> >> ><br>> >> > a> the requestor submits a patch to i18n repo<br>> >> > b> core team approve the patch<br>> >> > c> the auto uploading process is triggered. terminology.pot is uploaded<br>> >> > to<br>> >> > Zanata for translation<br>> >> > d> translators finish translation<br>> >> > e> Zanata admin manually patch terminology.pot and its translationpo<br>> >> > files,<br>> ><br>> >> > and upload to Zanata<br>> >><br>> >> IMO the glossary needs to be reviewed more carefully compared to<br>> >> regular translations.<br>> >> In regular translations, all translated strings are imported, but for<br>> >> glossary it is better that<br>> >> only reviewed strings are imported. Another choice is to use gerrit<br>> >> for the glossary review.<br>> >> My proposal <a href="https://review.openstack.org/261767">https://review.openstack.org/261767</a> implements the latter<br>> >> option.<br>> >><br>> >> Thought?<br>> >><br>> >> Thanks,<br>> >> Akihiro<br>> >><br>> >> ><br>> >> > Best regards<br>> >> > Ying Chun Guo (Daisy)<br>> >> ><br>> >> ><br>> >> > Akihiro Motoki <amotoki@gmail.com> wrote on 2015/12/02 02:29:44:<br>> >> ><br>> >> >> From: Akihiro Motoki <amotoki@gmail.com><br>> >> >> To: "openstack-i18n@lists.openstack.org"<br>> >> >> <Openstack-i18n@lists.openstack.org><br>> >> >> Date: 2015/12/02 02:32<br>> >> >> Subject: [Openstack-i18n] How do we manage glossary?<br>> >> ><br>> >> >><br>> >> >> Hi team,<br>> >> >><br>> >> >> Recently we added the glossary to the i18n repo [1].<br>> >> >> I wonder how we can manage the glossary and am sending this mail.<br>> >> >> The glossary can be referred to in Zanata, so it would be useful.<br>> >> >><br>> >> >> Mainly I have two questions.<br>> >> >><br>> >> >> The first point is what is the expected process to manage the glossary.<br>> >> >> How can we update the glossary?<br>> >> >> When is it uploaded to Zanata for translations?<br>> >> >><br>> >> >> The second point is how we can have the context.<br>> >> >> I think the second point is also important.<br>> >> >> Each entry in our glossary has some background, for example<br>> >> >> why we reach the current consensus.<br>> >> >> This kind of context is important to discuss for further improvements.<br>> >> >><br>> >> >> I updated the glossary for Japanese translation last week<br>> >> >> and I added various description about backgrounds of the glossary.<br>> >> >> I feel it is important to keep the context.<br>> >> >> How can we manage the context?<br>> >> >><br>> >> >> I don't have a good idea now.<br>> >> >> I would like to raise these questions for broader discussion.<br>> >> >><br>> >> >> Thanks,<br>> >> >> Akihiro<br>> >> >><br>> >> >> [1] <a href="http://git.openstack.org/cgit/openstack/i18n/tree/i18n">http://git.openstack.org/cgit/openstack/i18n/tree/i18n</a><br>> >> >><br>> >> >> _______________________________________________<br>> >> >> Openstack-i18n mailing list<br>> >> >> Openstack-i18n@lists.openstack.org<br>> >> >> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n</a><br>> >> >><br>> >> ><br>> >><br>> ><br>> <br></tt><BR>
</body></html>