[Openstack-i18n] How do we manage glossary - requirements priorities

SungJin Kang gang.sungjin at gmail.com
Thu Jan 14 17:02:46 UTC 2016


Hi,

um...

2016-01-11 18:36 GMT+09:00 Ying Chun Guo <guoyingc at cn.ibm.com>:

> Hello, team
>
> There are three possible solutions to manage glossaries and their
> translations.
> All of these solutions have their advantages and disadvantages.
> I think we should prioritize the requirements firstly, then we make the
> choice based on the requirements.
> Here I list some requirements.
>
> #1. Save glossaries in i18n repo
> #2. Translate and review with Zanata editor, and enable the auto sync
> between Zanata editor and i18n repo.
> #3. View comments while translating
> #4. Review the new added glossary by Gerrit
> #5. View the list of glossaries and their comments in i18n documents.
> #6. Keep the history of glossary translations and discussions.
>
+1
However, I think #3 is duble check. Zanata have littly review system.

>
> Please let me know your thoughts to these requirements.
> You can add comment "Must support", "good to have", and "not necessary" to
> each requirement,
> and order these requirements by the priority in your mind.
> If you have other requirements, feel free to add.
>
> For your reference, here are the three possible solutions:
>
> - Solution 1 Save glossaries in pot file and translations in po files.
> The current solution in repo: openstack/i18n
> Support requirement #1 , #2 and #4
> ( @Alex, please help to verify if #3 and #6 could be satisfied in this
> solution.)
>
not bad

>
> - Solution 2 Save glossaries in rst file and translations in po files.
> https://review.openstack.org/#/c/258924/
> Support requirement #1, #2, and #4, #5
>
 This +1 * 1000

> - Solution 3 Save glossaries in YAML file and translations in YAML files.
> https://review.openstack.org/#/c/261767/
> https://review.openstack.org/#/c/262710/
> Support requirement #1, #3 and #4, #6
>
um.. +1 * 10

Thanks.
Sungjin Kang

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


More information about the Openstack-i18n mailing list