Hi, I guess everyone translating has seen this, sometimes there's source text formatted by line breaks and even spaces at the beginning of lines which finally forces the translator to keep this format, else Zanata wouldn't allow to save it. For an example, see above :-) I think this formatting is rather bad and shouldn't happen. Text should be either continuous or it needs to be split to go into multiple strings. Are there any reasons where as such formatted text is justified, translator should leave it as it is? Or shall we rather rather flag this through a bug, or even create patches to change it? Opinions? -- Thanks, Robert
Several projects recently enhanced the help text for configuration options. In Glance, this has resulted in strings like [0] (and there are lots of other examples in that file). For those strings, the exact formatting isn't essential, but the paragraphing and bulleted lists are important. My question is whether having this text in a single block of triple-quotes (as it is now) is useful to translators (so you can see the entire context), or whether there's a way you'd prefer it to be broken up so that it works better with Zanata. When we added all these blocks of text in Newton, we were focused on making things easier for operators, and didn't realize that it would cause problems for translators ... sorry about that! thanks, brian [0] https://github.com/openstack/glance/blob/6b72fc3ef242f8572a581a09d082fd29f56... On 12/5/16 5:28 AM, Robert Simai wrote:
Hi,
I guess everyone translating has seen this, sometimes there's source text formatted by line breaks and even spaces at the beginning of lines which finally forces the translator to keep this format, else Zanata wouldn't allow to save it.
For an example, see above :-)
I think this formatting is rather bad and shouldn't happen. Text should be either continuous or it needs to be split to go into multiple strings.
Are there any reasons where as such formatted text is justified, translator should leave it as it is?
Or shall we rather rather flag this through a bug, or even create patches to change it?
Opinions?
Hi Brian, On Monday 05 December 2016, 09:42:21 Brian Rosmaita <rosmaita.fossdev@gmail.com> wrote:
Several projects recently enhanced the help text for configuration options. In Glance, this has resulted in strings like [0] (and there are lots of other examples in that file).
For those strings, the exact formatting isn't essential, but the paragraphing and bulleted lists are important.
I see and agree, this text will lose meaning without the format.
My question is whether having this text in a single block of triple-quotes (as it is now) is useful to translators (so you can see the entire context), or whether there's a way you'd prefer it to be broken up so that it works better with Zanata.
Looked up your example in Zanata and must say find it horrible to translate. But interestingly, Zanata at least allows to save the translation with just "warnings" (not errors), if the amount of lines doesn't match. I've seen this as real "errors" in other projects where you can only save as "fuzzy". However, looking at the text and its purpose, this is not for any GUI but console output and I guess that's why you limit line length to less than 72 characters, don't you? That would be a convention to clarify with the translators but isn't easy to achieve with the Zanata UI (it uses proportional fonts and has no counter). If the translator accidentally makes it 80+ characters it may easily kill the formatting. I may not help to put things into perspective for the translators but I finally think that the text block from your example is way too big and should be broken down to (many!) strings. The translator shouldn't need to take care of the amount of lines, line breaks, line lengths or leading spaces. Formatting, if desired, needs to happen at another place, within the application that does the output and may depend on screen details (e.g. terminal width for console stuff).
When we added all these blocks of text in Newton, we were focused on making things easier for operators, and didn't realize that it would cause problems for translators ... sorry about that!
Let's call it an inconvenience, not a problem ;-) -- Thanks, Robert
Hi Robert, On 12/6/16 3:34 AM, Robert Simai wrote:
Hi Brian,
On Monday 05 December 2016, 09:42:21 Brian Rosmaita <rosmaita.fossdev@gmail.com> wrote:
Several projects recently enhanced the help text for configuration options. In Glance, this has resulted in strings like [0] (and there are lots of other examples in that file).
For those strings, the exact formatting isn't essential, but the paragraphing and bulleted lists are important.
I see and agree, this text will lose meaning without the format.
My question is whether having this text in a single block of triple-quotes (as it is now) is useful to translators (so you can see the entire context), or whether there's a way you'd prefer it to be broken up so that it works better with Zanata.
Looked up your example in Zanata and must say find it horrible to translate. But interestingly, Zanata at least allows to save the translation with just "warnings" (not errors), if the amount of lines doesn't match. I've seen this as real "errors" in other projects where you can only save as "fuzzy".
However, looking at the text and its purpose, this is not for any GUI but console output and I guess that's why you limit line length to less than 72 characters, don't you? That would be a convention to clarify with the translators but isn't easy to achieve with the Zanata UI (it uses proportional fonts and has no counter). If the translator accidentally makes it 80+ characters it may easily kill the formatting.
Here's the situation. We're using oslo.config to define configuration options and generate sample config files. We've decided to put the help text at the point where the option is defined so that there will be a single place where the text is maintained. So those strings are actually documentation ... and I didn't realize until now that by enclosing those strings in _(), we're asking you to translate *documentation*, not log lines or error messages, which may not be what you've signed up for. As far as the line length goes, we just need to keep it short enough to conform to the openstack python coding convention (79 char lines). So as long as the paragraphing is kept, I don't think the line length would matter. In any case, I guess the question now is whether these help text strings should be marked for translation in the first place.
I may not help to put things into perspective for the translators but I finally think that the text block from your example is way too big and should be broken down to (many!) strings. The translator shouldn't need to take care of the amount of lines, line breaks, line lengths or leading spaces. Formatting, if desired, needs to happen at another place, within the application that does the output and may depend on screen details (e.g. terminal width for console stuff).
The strings are actually marked up as RST (re-structured text), using a limited set of tags. In order to encourage developers to write good documentation when adding config options, we're trying to keep the requirements as simple as possible. We could break things into a series of strings, but we'd like to keep developers focused on writing good content -- if the format in which you've got to write these things gets too complicated, I'm afraid it will cause "inconveniences" on the development side and make it more difficult to get good docs.
When we added all these blocks of text in Newton, we were focused on making things easier for operators, and didn't realize that it would cause problems for translators ... sorry about that!
Let's call it an inconvenience, not a problem ;-)
Sounds good! Let's continue the discussion to figure out how to make this more convenient for all concerned. cheers, brian
On Tuesday 06 December 2016, 09:21:42 Brian Rosmaita <rosmaita.fossdev@gmail.com> wrote:
On 12/6/16 3:34 AM, Robert Simai wrote:
On Monday 05 December 2016, 09:42:21 Brian Rosmaita <rosmaita.fossdev@gmail.com> wrote:
[...]
In any case, I guess the question now is whether these help text strings should be marked for translation in the first place.
Probably that's the pragmatic and right question which finally is more about the benefit in translating CLI apps, their terminal or log outputs. I guess you opened up another discussion point here but if you want my 0.02$, let's not do it. It's creating more issues that it helps. We actually mostly focus on UI text for translations and that's where I made my observations. Still looking for opinions from my translator peers ... [...] -- Thanks, Robert
Hello Robert & Brian, Thanks a lot for bringing up the issue with discussion. There were other kind of number of a little bit annoying spaces to translators mainly in Horizon strings. I had seen a number of such cases previously, but recently I do not see such cases. One example is shown in openstack_dashboard po files in Mitaka and master - Mitaka (German): http://git.openstack.org/cgit/openstack/horizon/tree/openstack_dashboard/loc... - master (German):http://git.openstack.org/cgit/openstack/horizon/tree/openstack_dashboard/loc... After investigating more on such cases, I have found that such kind of spaces was solved by Akihiro-san: https://bugs.launchpad.net/horizon/+bug/1583757 . So, if you find a number of spaces in current Horizon strings, it would be much better to change "{% blocktrans %}" to "{% blocktrans trimmed %}" in corresponding HTML file(s). So, please share it to i18n team members or report it as a bug in Horizon with "i18n" tag. Brian Rosmaita wrote on 12/6/2016 11:21 PM:
Hi Robert,
Hi Brian,
On Monday 05 December 2016, 09:42:21 Brian Rosmaita <rosmaita.fossdev@gmail.com> wrote:
Several projects recently enhanced the help text for configuration options. In Glance, this has resulted in strings like [0] (and there are lots of other examples in that file).
For those strings, the exact formatting isn't essential, but the paragraphing and bulleted lists are important. I see and agree, this text will lose meaning without the format.
My question is whether having this text in a single block of triple-quotes (as it is now) is useful to translators (so you can see the entire context), or whether there's a way you'd prefer it to be broken up so that it works better with Zanata. Looked up your example in Zanata and must say find it horrible to translate. But interestingly, Zanata at least allows to save the translation with just "warnings" (not errors), if the amount of lines doesn't match. I've seen this as real "errors" in other projects where you can only save as "fuzzy".
However, looking at the text and its purpose, this is not for any GUI but console output and I guess that's why you limit line length to less than 72 characters, don't you? That would be a convention to clarify with the translators but isn't easy to achieve with the Zanata UI (it uses proportional fonts and has no counter). If the translator accidentally makes it 80+ characters it may easily kill the formatting. Here's the situation. We're using oslo.config to define configuration
On 12/6/16 3:34 AM, Robert Simai wrote: options and generate sample config files. We've decided to put the help text at the point where the option is defined so that there will be a single place where the text is maintained. So those strings are actually documentation ... and I didn't realize until now that by enclosing those strings in _(), we're asking you to translate *documentation*, not log lines or error messages, which may not be what you've signed up for.
As far as the line length goes, we just need to keep it short enough to conform to the openstack python coding convention (79 char lines). So as long as the paragraphing is kept, I don't think the line length would matter.
In any case, I guess the question now is whether these help text strings should be marked for translation in the first place. Currently, I18n team does not focus on translating development documents seen in http://developer.o.o/developer/ sub pages, since translating user-facing projects (e.g., Horizon) and documentations for beginners and user sides (e.g., install-guide) has higher priority.
But now I18n team would like to translate I18n contributor guide ( http://docs.openstack.org/developer/i18n/ ). To accomplish this, adding translation support on this document is needed. After then, I think more development documentations will be considered with translation using Zanata. I am not currently sure how help text strings will be rendered into development documents. For example, the description part for glance-manage http://docs.openstack.org/developer/glance/man/glancemanage.html is managed in Python source files, rather than in rst files? As Robert mentioned, translating even log and/or error messages is not a good idea because more people would like to find root causes by searching the log and/or error messages on the Internet, and even asking such messages through mailing lists and IRC channels would be easier. But IMO translating help texts is nice :) With many thanks, /Ian
I may not help to put things into perspective for the translators but I finally think that the text block from your example is way too big and should be broken down to (many!) strings. The translator shouldn't need to take care of the amount of lines, line breaks, line lengths or leading spaces. Formatting, if desired, needs to happen at another place, within the application that does the output and may depend on screen details (e.g. terminal width for console stuff). The strings are actually marked up as RST (re-structured text), using a limited set of tags. In order to encourage developers to write good documentation when adding config options, we're trying to keep the requirements as simple as possible. We could break things into a series of strings, but we'd like to keep developers focused on writing good content -- if the format in which you've got to write these things gets too complicated, I'm afraid it will cause "inconveniences" on the development side and make it more difficult to get good docs.
When we added all these blocks of text in Newton, we were focused on making things easier for operators, and didn't realize that it would cause problems for translators ... sorry about that! Let's call it an inconvenience, not a problem ;-)
Sounds good! Let's continue the discussion to figure out how to make this more convenient for all concerned.
cheers, brian
_______________________________________________ OpenStack-I18n mailing list OpenStack-I18n@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
Hi Ian, the example I'm talking about is in horizon/openstack_dashboard/dashboards/project/static/dashboard/project/containers/create-container-modal.html which becomes "A floating IP allows instances to be addressable from an external network.\n" " Floating IPs are not allocated to instances at creation time and may be " "assigned\n" " after the instance is created. To attach a floating IP, go to the " in the djangojs.po files and that's what I finally see in Zanata. I checked in a Horizon installation and it seems there's no need for formatting the text. I guess I'll report this as a bug then. -- Thanks, Robert On Thursday 08 December 2016, 02:06:28 Ian Y. Choi <ianyrchoi@gmail.com> wrote:
Hello Robert & Brian,
Thanks a lot for bringing up the issue with discussion.
There were other kind of number of a little bit annoying spaces to translators mainly in Horizon strings. I had seen a number of such cases previously, but recently I do not see such cases.
One example is shown in openstack_dashboard po files in Mitaka and master - Mitaka (German): http://git.openstack.org/cgit/openstack/horizon/tree/openstack_dashboard/l ocale/de/LC_MESSAGES/django.po?h=stable/mitaka#n21 - master (German):http://git.openstack.org/cgit/openstack/horizon/tree/openstack_da shboard/locale/de/LC_MESSAGES/django.po#n169
After investigating more on such cases, I have found that such kind of spaces was solved by Akihiro-san: https://bugs.launchpad.net/horizon/+bug/1583757 .
So, if you find a number of spaces in current Horizon strings, it would be much better to change "{% blocktrans %}" to "{% blocktrans trimmed %}" in corresponding HTML file(s). So, please share it to i18n team members or report it as a bug in Horizon with "i18n" tag.
Brian Rosmaita wrote on 12/6/2016 11:21 PM:
Hi Robert,
On 12/6/16 3:34 AM, Robert Simai wrote:
Hi Brian,
On Monday 05 December 2016, 09:42:21 Brian Rosmaita
<rosmaita.fossdev@gmail.com> wrote:
Several projects recently enhanced the help text for configuration options. In Glance, this has resulted in strings like [0] (and there are lots of other examples in that file).
For those strings, the exact formatting isn't essential, but the paragraphing and bulleted lists are important.
I see and agree, this text will lose meaning without the format.
My question is whether having this text in a single block of triple-quotes (as it is now) is useful to translators (so you can see the entire context), or whether there's a way you'd prefer it to be broken up so that it works better with Zanata.
Looked up your example in Zanata and must say find it horrible to translate. But interestingly, Zanata at least allows to save the translation with just "warnings" (not errors), if the amount of lines doesn't match. I've seen this as real "errors" in other projects where you can only save as "fuzzy".
However, looking at the text and its purpose, this is not for any GUI but console output and I guess that's why you limit line length to less than 72 characters, don't you? That would be a convention to clarify with the translators but isn't easy to achieve with the Zanata UI (it uses proportional fonts and has no counter). If the translator accidentally makes it 80+ characters it may easily kill the formatting.
Here's the situation. We're using oslo.config to define configuration options and generate sample config files. We've decided to put the help text at the point where the option is defined so that there will be a single place where the text is maintained. So those strings are actually documentation ... and I didn't realize until now that by enclosing those strings in _(), we're asking you to translate *documentation*, not log lines or error messages, which may not be what you've signed up for.
As far as the line length goes, we just need to keep it short enough to conform to the openstack python coding convention (79 char lines). So as long as the paragraphing is kept, I don't think the line length would matter.
In any case, I guess the question now is whether these help text strings should be marked for translation in the first place.
Currently, I18n team does not focus on translating development documents seen in http://developer.o.o/developer/ sub pages, since translating user-facing projects (e.g., Horizon) and documentations for beginners and user sides (e.g., install-guide) has higher priority.
But now I18n team would like to translate I18n contributor guide ( http://docs.openstack.org/developer/i18n/ ). To accomplish this, adding translation support on this document is needed. After then, I think more development documentations will be considered with translation using Zanata.
I am not currently sure how help text strings will be rendered into development documents. For example, the description part for glance-manage http://docs.openstack.org/developer/glance/man/glancemanage.html is managed in Python source files, rather than in rst files?
As Robert mentioned, translating even log and/or error messages is not a good idea because more people would like to find root causes by searching the log and/or error messages on the Internet, and even asking such messages through mailing lists and IRC channels would be easier. But IMO translating help texts is nice :)
With many thanks,
/Ian
I may not help to put things into perspective for the translators but I finally think that the text block from your example is way too big and should be broken down to (many!) strings. The translator shouldn't need to take care of the amount of lines, line breaks, line lengths or leading spaces. Formatting, if desired, needs to happen at another place, within the application that does the output and may depend on screen details (e.g. terminal width for console stuff).
The strings are actually marked up as RST (re-structured text), using a limited set of tags. In order to encourage developers to write good documentation when adding config options, we're trying to keep the requirements as simple as possible. We could break things into a series of strings, but we'd like to keep developers focused on writing good content -- if the format in which you've got to write these things gets too complicated, I'm afraid it will cause "inconveniences" on the development side and make it more difficult to get good docs.
When we added all these blocks of text in Newton, we were focused on making things easier for operators, and didn't realize that it would cause problems for translators ... sorry about that!
Let's call it an inconvenience, not a problem ;-)
Sounds good! Let's continue the discussion to figure out how to make this more convenient for all concerned.
cheers, brian
_______________________________________________ OpenStack-I18n mailing list OpenStack-I18n@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
participants (3)
-
Brian Rosmaita
-
Ian Y. Choi
-
Robert Simai