Open Stack

Thanks for initiating the effort.

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.
>

I would like to suggest to distinguish "master glossary" (in the
source language)
and "per-language glossary" in this discussion.

Theoretically speaking, each language team can have its own glossary, but
IIUC Zanata glossary does not allows it and we need to have a common
glossary entries.
As the assumption of this discussion, should we assume the current
enabled feature in Zanata
or can we assume to enhancing Zanata?

I would suggest to distinguish 'requirements' and the current
limitation of Zanata.
'requirement' should not have assumption based on 'the current
limitation of Zanata'.

Now, I am looking through the listed items.

#0 each language team can manage their glossary without 'admin' role.
At least, language coordinator and reviewers should be allowed to do it.

To me, this is the top priority "must to have".

> #1. Save glossaries in i18n repo

"nice to have"

"master" or "per-language"?
Based on #2 below, it seems "master glossary".

> #2. Translate and review with Zanata editor, and enable the auto sync
> between Zanata editor and i18n repo.

In #2, it seems two things are mixed.
The first part "Translate and review with Zanata editor", yes it is a
requirement.
The second part is just a process. It is not a requirement, i.e.,
"nice to have".

> #3. View comments while translating

"Must to have" (as the second priority)

I believe it is "Must to have" but it is not a top priority
because the top priority to me is that each language is allowed to
maintain their glossary without 'admin' privilege.

> #4. Review the new added glossary by Gerrit

"not necessary"

I am not sure this needs to be done in Gerrit.
If we have a way to add a new entry in Zanata, it is sufficient as well.
I am not sure what assumption you have.

> #5. View the list of glossaries and their comments in i18n documents.

"not necessary"
I don't think it is a requirement.

I hope the list of glossary on Zanata instead as Transfix does.
When we go to "Glossary" link at the top of Zanata UI
https://translate.openstack.org/glossary/view.seam,
we see a list of languages but when we click a language name,
we will get a list of members of each language team.
It is a confusing behavior and we expect a glossary in each language.

> #6. Keep the history of glossary translations and discussions.

"must to have" (as the second priority)
Yes. this is important!

>
> 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.

/FYI/ I abandoned my reviews to keep my review list small.
Feel free to restore them if necessary even after this discussion have
a consensus.

Thanks,
Akihiro

>
> 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.)
>
> - 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
>
> - 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
>
> 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
>> >> >>
>> >> >
>> >>
>> >
>>
>