Hi, Andreas, Daisy, Motoki-san and myself have just had an impromptu hour-long discussion regarding the Status of the RST Documentation Toolchain, particularly its translation components. This meeting was spurred on by the email to the i18n mailing list announcing the pending removal of docbook user guides, and all present acknowledged the meeting would have been great if it had happened sooner :) This is the brief summary! 1. Everyone involved wants to make translators happy, and hopes that the process of moving to RST can deliver an improved toolchain 2. There has been inadequate communication between the documentation team and the i18n team regarding requirements and timelines during this process and we will strive to improve this 3. Previous statement that RST-based docs would not be published without agreement on the translation toolchain was acknowledged 4. Based on the user guide example, about 50% of existing translated strings (1943 vs 943) need to be re-translated with the current conversion process 5. Noone on the i18n team had yet the opportunity to assess the strings produced by the RST in a fuller guide and problems weren't picked up with initial version of guides in the playground folder 6. Daisy in particular hasn't been able to log in to transifex today to check the new user guide. We are currently using the standard Sphinx translation tools, though, there was some definite concern over the quality of the strings produced by the RST, including: 1. Strings that should have been trivially updated during conversion from docbook without human interaction needed (eg **string**\n) 2. Strings that are entirely markup (eg :ref:`Boot_instance_from_image_and_attach_non-bootable_volume`) 3. Strings that contain significant amounts of markup 4. Strings that contain markup characters that are unusual for translations, eg backticks, asterisks 5. Strings that contain markup where placeholders were previously used 6. ... this list is incomplete and comes only from what amotoki and fifieldt saw during the meeting - the broader i18n community has not yet been asked for feedback outside of Andreas' recent email 7. There is an open issue about how to fix problems like the above. 1. Andreas stated that not maintaining our own custom scripts is a good aim, and some of the issues above could be handled with a one time fix at conversion time 2. Daisy & Tom stated that they preferred such issues to be fixed in the toolchain 3. Just looking at the "** STRING **" issue, it's 70 strings but a quick proof of concept didn't result in fixing the issue - we haven't worked out why yet. 4. The current toolchain is difficult to modify, since it relies on an upstream component that is used by multiple projects, meaning post processing and pre-processing are the only real approach we have 5. It could be complicated to use post-processing and pre-processing to implement fixes for issues beyond the trivially updated string example in the current toolchain 8. There is an open question about whether it is possible to deliver an improved i18n experience with the current toolchain 9. There is not yet agreement that the current documentation toolchain is meeting the needs of the i18n team Based on the meeting, and especially the fact that due to inadequate communication the i18n team (inc Daisy) has not yet had the opportunity to assess the RST documentation toolchain fully, I would propose that the removal of existing guides and publication of RST guides be delayed until that's happened. We suggest that Daisy does an initial assessment and arrange a meeting to discuss next steps as soon as possible.There are many things we can fix with the the toolchain any time after publication, however it is important that we assess what needs to be done and ensure that we can actually feasibly deliver an improved experience for our translations, as well as our doc team. Regards, Tom
Thanks Tom. On Thu, Apr 9, 2015 at 4:09 AM, Tom Fifield <tom@openstack.org> wrote:
Hi,
Andreas, Daisy, Motoki-san and myself have just had an impromptu hour-long discussion regarding the Status of the RST Documentation Toolchain, particularly its translation components. This meeting was spurred on by the email to the i18n mailing list announcing the pending removal of docbook user guides, and all present acknowledged the meeting would have been great if it had happened sooner :) This is the brief summary!
1. Everyone involved wants to make translators happy, and hopes that the process of moving to RST can deliver an improved toolchain
1. There has been inadequate communication between the documentation team and the i18n team regarding requirements and timelines during this process and we will strive to improve this
1. Previous statement that RST-based docs would not be published without agreement on the translation toolchain was acknowledged
1. Based on the user guide example, about 50% of existing translated strings (1943 vs 943) need to be re-translated with the current conversion process
1. Noone on the i18n team had yet the opportunity to assess the strings produced by the RST in a fuller guide and problems weren't picked up with initial version of guides in the playground folder
1. Daisy in particular hasn't been able to log in to transifex today to check the new user guide. We are currently using the standard Sphinx translation tools, though, there was some definite concern over the quality of the strings produced by the RST, including:
1. Strings that should have been trivially updated during conversion from docbook without human interaction needed (eg **string**\n)
1. Strings that are entirely markup (eg :ref:`Boot_instance_from_image_and_attach_non-bootable_volume`)
1. Strings that contain significant amounts of markup
1. Strings that contain markup characters that are unusual for translations, eg backticks, asterisks
1. Strings that contain markup where placeholders were previously used
1. ... this list is incomplete and comes only from what amotoki and fifieldt saw during the meeting - the broader i18n community has not yet been asked for feedback outside of Andreas' recent email
1. There is an open issue about how to fix problems like the above.
1. Andreas stated that not maintaining our own custom scripts is a good aim, and some of the issues above could be handled with a one time fix at conversion time
1. Daisy & Tom stated that they preferred such issues to be fixed in the toolchain
1. Just looking at the "** STRING **" issue, it's 70 strings but a quick proof of concept didn't result in fixing the issue - we haven't worked out why yet.
1. The current toolchain is difficult to modify, since it relies on an upstream component that is used by multiple projects, meaning post processing and pre-processing are the only real approach we have
1. It could be complicated to use post-processing and pre-processing to implement fixes for issues beyond the trivially updated string example in the current toolchain
1. There is an open question about whether it is possible to deliver an improved i18n experience with the current toolchain
1. There is not yet agreement that the current documentation toolchain is meeting the needs of the i18n team
Happy to dig into this further, and we'll work through issues before publishing. I have to drive four hours today so I won't be online much, but I apologize for the scramble and will continue to work with the teams. Thanks, Anne
Based on the meeting, and especially the fact that due to inadequate communication the i18n team (inc Daisy) has not yet had the opportunity to assess the RST documentation toolchain fully, I would propose that the removal of existing guides and publication of RST guides be delayed until that's happened. We suggest that Daisy does an initial assessment and arrange a meeting to discuss next steps as soon as possible. There are many things we can fix with the the toolchain any time after publication, however it is important that we assess what needs to be done and ensure that we can actually feasibly deliver an improved experience for our translations, as well as our doc team.
Regards,
Tom
_______________________________________________ OpenStack-docs mailing list OpenStack-docs@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
-- Anne Gentle annegentle@justwriteclick.com
Tom Fifield <tom@openstack.org> wrote on 2015/04/09 17:09:17:
From: Tom Fifield <tom@openstack.org> To: "openstack-docs@lists.openstack.org" <openstack- docs@lists.openstack.org>, "openstack-i18n@lists.openstack.org" <openstack-i18n@lists.openstack.org> Date: 2015/04/09 17:09 Subject: [Openstack-i18n] Status of the RST Documentation Toolchain
Hi,
Andreas, Daisy, Motoki-san and myself have just had an impromptu hour-long discussion regarding the Status of the RST Documentation Toolchain, particularly its translation components. This meeting was spurred on by the email to the i18n mailing list announcing the pending removal of docbook user guides, and all present acknowledged the meeting would have been great if it had happened sooner :) This is the brief summary!
1. Everyone involved wants to make translators happy, and hopes that the process of moving to RST can deliver an improved toolchain 2. There has been inadequate communication between the documentation team and the i18n team regarding requirements and timelines during this process and we will strive to improve this 3. Previous statement that RST-based docs would not be published without agreement on the translation toolchain was acknowledged 4. Based on the user guide example, about 50% of existing translated strings (1943 vs 943) need to be re-translated with the current conversion process 5. Noone on the i18n team had yet the opportunity to assess the strings produced by the RST in a fuller guide and problems weren't picked up with initial version of guides in the playground folder 6. Daisy in particular hasn't been able to log in to transifex today to check the new user guide. We are currently using the standard Sphinx translation tools, though, there was some definite concern over the quality of the strings produced by the RST, including: 1. Strings that should have been trivially updated during conversion from docbook without human interaction needed (eg **string**\n) 2. Strings that are entirely markup (eg :ref:`Boot_instance_from_image_and_attach_non-bootable_volume`) 3. Strings that contain significant amounts of markup 4. Strings that contain markup characters that are unusual for translations, eg backticks, asterisks 5. Strings that contain markup where placeholders were previously used 6. ... this list is incomplete and comes only from what amotoki and fifieldt saw during the meeting - the broader i18n community has not yet been asked for feedback outside of Andreas' recent email 7. There is an open issue about how to fix problems like the above. 1. Andreas stated that not maintaining our own custom scripts is a good aim, and some of the issues above could be handled with a one time fix at conversion time 2. Daisy & Tom stated that they preferred such issues to be fixed in the toolchain 3. Just looking at the "** STRING **" issue, it's 70 strings but a quick proof of concept didn't result in fixing the issue - we haven't worked out why yet. 4. The current toolchain is difficult to modify, since it relies on an upstream component that is used by multiple projects, meaning post processing and pre-processing are the only real approach we have 5. It could be complicated to use post-processing and pre-processing to implement fixes for issues beyond the trivially updated string example in the current toolchain 8. There is an open question about whether it is possible to deliver an improved i18n experience with the current toolchain 9. There is not yet agreement that the current documentation toolchain is meeting the needs of the i18n team
Based on the meeting, and especially the fact that due to inadequate communication the i18n team (inc Daisy) has not yet had the opportunity to assess the RST documentation toolchain fully, I would propose that the removal of existing guides and publication of RST guides be delayed until that's happened.
I investigated the translation process of RST document, asked by Anne and Andreas. While I made test, I used playground-user-guide, which was a quite new document. I didn't pay attention to the pot content changes between the old version and the new version. I'm quite sorry for that. I don't want to block anything. In my mind, the toolchain could be improved continuously, both before publication and after publication.
We suggest that Daisy does an initial assessment and arrange a meeting to discuss next steps as soon as possible. There are many things we can fix with the the toolchain any time after publication, however it is important that we assess what needs to be done and ensure that we can actually feasibly deliver an improved experience for our translations, as well as our doc team.
Regards,
Tom _______________________________________________ Openstack-i18n mailing list Openstack-i18n@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
On 04/09/2015 02:16 PM, Ying Chun Guo wrote:
[...] I investigated the translation process of RST document, asked by Anne and Andreas. While I made test, I used playground-user-guide, which was a quite new document. I didn't pay attention to the pot content changes between the old version and the new version. I'm quite sorry for that. I don't want to block anything. In my mind, the toolchain could be improved continuously, both before publication and after publication.
With the analysis done by Daisy [1] (thanks!) and my scripted updates to convert automatically what was possible [2] thus raising the number of translated strings for Japanese on the User Guides from 32 % to 37 %, and my patch for building the Japanese tools we have IMHO done everything we can do. Or has anybody suggestions for additional things to do now? If not, I think we're good to publish the new RST User Guides. So, I propose these next steps: * Get explicit ok by Daisy that we can continue based on her findings * Review and merge patch [3] * Anne decides when to publish User Guides Andreas [1] http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html [2] http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001034.html [3] https://review.openstack.org/162424 -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
Here are my thoughts. 1. I would like the toolchain could be extendable for the future improvement. If we are able to make small and easy improvements before publishing, like handling double stars and double colons (described in [1]), let's do that. In the future, let's continue the improvement. The goal is to provide an easily understandable source strings for translators. 2. I would like the translators to be well educated about the RST markups. I will covert [2] into translators' view. ( I don't think translators would read through this long document to pick out RST markups. ) Clearly list RST markups, give samples, and describe the meanings. Thus the translators could easily understand which words and punctuation characters should not be translated and need to keep them unchanged carefully. 3. Next Thursday, I will have the team meeting with the translators. I will collect their feedback to these RST markups. @ Andreas and Anne, let me know your feeling tho these thoughts. Daisy [1] http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html [2] https://wiki.openstack.org/wiki/Documentation/Markup_conventions Andreas Jaeger <aj@suse.com> wrote on 2015/04/10 12:38:21:
From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN Cc: "openstack-i18n@lists.openstack.org" <openstack- i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/04/10 12:38 Subject: Re: [OpenStack-docs] [Openstack-i18n] Status of the RST Documentation Toolchain
On 04/09/2015 02:16 PM, Ying Chun Guo wrote:
[...] I investigated the translation process of RST document, asked by Anne and Andreas. While I made test, I used playground-user-guide, which was a quite new document. I didn't pay attention to the pot content changes between the old version and the new version. I'm quite sorry for that. I don't want to block anything. In my mind, the toolchain could be improved continuously, both before publication and after publication.
With the analysis done by Daisy [1] (thanks!) and my scripted updates to convert automatically what was possible [2] thus raising the number of translated strings for Japanese on the User Guides from 32 % to 37 %, and my patch for building the Japanese tools we have IMHO done everything we can do.
Or has anybody suggestions for additional things to do now?
If not, I think we're good to publish the new RST User Guides.
So, I propose these next steps: * Get explicit ok by Daisy that we can continue based on her findings * Review and merge patch [3] * Anne decides when to publish User Guides
Andreas
[1]
http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html
[2]
http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001034.html
[3] https://review.openstack.org/162424 -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
On 04/10/2015 11:04 AM, Ying Chun Guo wrote:
Here are my thoughts.
1. I would like the toolchain could be extendable for the future improvement. If we are able to make small and easy improvements before publishing, like handling double stars and double colons (described in [1]), let's do that. In the future, let's continue the improvement. The goal is to provide an easily understandable source strings for translators.
I don't have a good idea how to convert transformations back like stars and double colons. If anybody comes up with commands on how to do it, I'll happily integrate them into the toolchain.
2. I would like the translators to be well educated about the RST markups. I will covert [2] into translators' view. ( I don't think translators would read through this long document to pick out RST markups. ) Clearly list RST markups, give samples, and describe the meanings. Thus the translators could easily understand which words and punctuation characters should not be translated and need to keep them unchanged carefully.
There are already quite a few tutorials on RST, perhaps it's better to reference these instead of writing a new one?
3. Next Thursday, I will have the team meeting with the translators. I will collect their feedback to these RST markups.
@ Andreas and Anne, let me know your feeling tho these thoughts.
Andreas
Daisy
[1] http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html [2] https://wiki.openstack.org/wiki/Documentation/Markup_conventions
Andreas Jaeger <aj@suse.com> wrote on 2015/04/10 12:38:21:
From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN Cc: "openstack-i18n@lists.openstack.org" <openstack- i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/04/10 12:38 Subject: Re: [OpenStack-docs] [Openstack-i18n] Status of the RST Documentation Toolchain
On 04/09/2015 02:16 PM, Ying Chun Guo wrote:
[...] I investigated the translation process of RST document, asked by Anne and Andreas. While I made test, I used playground-user-guide, which was a quite new document. I didn't pay attention to the pot content changes between the old version and the new version. I'm quite sorry for that. I don't want to block anything. In my mind, the toolchain could be improved continuously, both before publication and after publication.
With the analysis done by Daisy [1] (thanks!) and my scripted updates to convert automatically what was possible [2] thus raising the number of translated strings for Japanese on the User Guides from 32 % to 37 %, and my patch for building the Japanese tools we have IMHO done everything we can do.
Or has anybody suggestions for additional things to do now?
If not, I think we're good to publish the new RST User Guides.
So, I propose these next steps: * Get explicit ok by Daisy that we can continue based on her findings * Review and merge patch [3] * Anne decides when to publish User Guides
Andreas
[1]
http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html
[2]
http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001034.html
[3] https://review.openstack.org/162424 -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
-- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
There are already quite a few tutorials on RST, perhaps it's better to reference these instead of writing a new one?
To me, an absolute newcomer, the overview on the Sphinx web site and the markup conventions page in the wiki (https://wiki.openstack.org/wiki/Documentation/Markup_conventions) were sufficient to understand RST. What might be useful is a pocket reference of those RST markups that we want to use in our docs, perhaps added to the wiki page. Bernd -----Original Message----- From: Andreas Jaeger [mailto:aj@suse.com] Sent: Friday, April 10, 2015 6:36 PM To: Ying Chun Guo Cc: openstack-i18n@lists.openstack.org; openstack-docs@lists.openstack.org Subject: Re: [OpenStack-docs] [Openstack-i18n] Status of the RST Documentation Toolchain On 04/10/2015 11:04 AM, Ying Chun Guo wrote:
Here are my thoughts.
1. I would like the toolchain could be extendable for the future improvement. If we are able to make small and easy improvements before publishing, like handling double stars and double colons (described in [1]), let's do that. In the future, let's continue the improvement. The goal is to provide an easily understandable source strings for translators.
I don't have a good idea how to convert transformations back like stars and double colons. If anybody comes up with commands on how to do it, I'll happily integrate them into the toolchain.
2. I would like the translators to be well educated about the RST markups. I will covert [2] into translators' view. ( I don't think translators would read through this long document to pick out RST markups. ) Clearly list RST markups, give samples, and describe the meanings. Thus the translators could easily understand which words and punctuation characters should not be translated and need to keep them unchanged carefully.
3. Next Thursday, I will have the team meeting with the translators. I will collect their feedback to these RST markups.
@ Andreas and Anne, let me know your feeling tho these thoughts.
Andreas
Daisy
[1] http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html [2] https://wiki.openstack.org/wiki/Documentation/Markup_conventions
Andreas Jaeger <aj@suse.com> wrote on 2015/04/10 12:38:21:
From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN Cc: "openstack-i18n@lists.openstack.org" <openstack- i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/04/10 12:38 Subject: Re: [OpenStack-docs] [Openstack-i18n] Status of the RST Documentation Toolchain
On 04/09/2015 02:16 PM, Ying Chun Guo wrote:
[...] I investigated the translation process of RST document, asked by Anne and Andreas. While I made test, I used playground-user-guide, which was a quite
new
document. I didn't pay attention to the pot content changes between the old version and the new version. I'm quite sorry for that. I don't want to block anything. In my mind, the toolchain could be improved continuously, both before publication and after publication.
With the analysis done by Daisy [1] (thanks!) and my scripted updates to convert automatically what was possible [2] thus raising the number of translated strings for Japanese on the User Guides from 32 % to 37 %, and my patch for building the Japanese tools we have IMHO done everything we can do.
Or has anybody suggestions for additional things to do now?
If not, I think we're good to publish the new RST User Guides.
So, I propose these next steps: * Get explicit ok by Daisy that we can continue based on her findings * Review and merge patch [3] * Anne decides when to publish User Guides
Andreas
[1]
http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html
[2]
http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001034.html
[3] https://review.openstack.org/162424 -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
-- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 _______________________________________________ OpenStack-docs mailing list OpenStack-docs@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
On 2015-04-10 23:18:21 +0900 (+0900), Bernd Bausch wrote: [...]
What might be useful is a pocket reference of those RST markups that we want to use in our docs, perhaps added to the wiki page.
See <http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt> -- Jeremy Stanley
Thank you all for the inputs. I have created a wiki page for translators to reference. https://wiki.openstack.org/wiki/I18nTeam/rst-markups If I missed any topical markups used in our manuals, please let me know. Jeremy Stanley <fungi@yuggoth.org> wrote on 2015/04/11 00:11:09:
From: Jeremy Stanley <fungi@yuggoth.org> To: openstack-i18n@lists.openstack.org, openstack-docs@lists.openstack.org Date: 2015/04/11 00:11 Subject: Re: [Openstack-i18n] [OpenStack-docs] Status of the RST Documentation Toolchain
On 2015-04-10 23:18:21 +0900 (+0900), Bernd Bausch wrote: [...]
What might be useful is a pocket reference of those RST markups that we want to use in our docs, perhaps added to the wiki page.
See <http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt> -- Jeremy Stanley
_______________________________________________ Openstack-i18n mailing list Openstack-i18n@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
Hello, There was a meeting with translators in IRC. Andreas Jaeger and Lana Brindley from doc team attended. François Bureau from French team, SungJin Kang from Korean team and myself from Chinese team attended the meeting. Firstly, Andreas confirmed that the tool chain was extendable. The preprocessing of po/pot before translation could be implemented in tools/generatepot-rst.sh. The postprocessing of po after translation could be done either as part of the building process, or as part of the infra scripts - propose_translation_update_manuals.sh . Then we talked about how to translate those strings with rst markups. rst markups are more difficult to identified than XML tags. That's why a translators RST cheat sheet is needed. Andreas and Lana explained some markups to translators. At last, all the attendees from translation teams were fine with the rst conversion. I will continue to maintain the translators cheat sheet. If doc writers introduce new mark ups, don't forget to add to the cheat sheet. The sheet can help the new translators easily understand how to translate. I think we got the agreement to go on. Many thanks to the attendees. Best regards Ying Chun Guo (Daisy) Ying Chun Guo/China/IBM@IBMCN wrote on 2015/04/10 17:04:38:
From: Ying Chun Guo/China/IBM@IBMCN To: Andreas Jaeger <aj@suse.com> Cc: "openstack-i18n@lists.openstack.org" <openstack- i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/04/10 17:09 Subject: Re: [OpenStack-docs] [Openstack-i18n] Status of the RST Documentation Toolchain
Here are my thoughts.
1. I would like the toolchain could be extendable for the future improvement. If we are able to make small and easy improvements before publishing, like handling double stars and double colons (described in [1]), let's do that. In the future, let's continue the improvement. The goal is to provide an easily understandable source strings for translators.
2. I would like the translators to be well educated about the RST markups. I will covert [2] into translators' view. ( I don't think translators would read through this long document to pick out RST markups. ) Clearly list RST markups, give samples, and describe the meanings. Thus the translators could easily understand which words and punctuation characters should not be translated and need to keep them unchanged carefully.
3. Next Thursday, I will have the team meeting with the translators. I will collect their feedback to these RST markups.
@ Andreas and Anne, let me know your feeling tho these thoughts.
Daisy
[1] http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html [2] https://wiki.openstack.org/wiki/Documentation/Markup_conventions
Andreas Jaeger <aj@suse.com> wrote on 2015/04/10 12:38:21:
From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN Cc: "openstack-i18n@lists.openstack.org" <openstack- i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/04/10 12:38 Subject: Re: [OpenStack-docs] [Openstack-i18n] Status of the RST Documentation Toolchain
On 04/09/2015 02:16 PM, Ying Chun Guo wrote:
[...] I investigated the translation process of RST document, asked by Anne and Andreas. While I made test, I used playground-user-guide, which was a quite new document. I didn't pay attention to the pot content changes between the old version and the new version. I'm quite sorry for that. I don't want to block anything. In my mind, the toolchain could be improved continuously, both before publication and after publication.
With the analysis done by Daisy [1] (thanks!) and my scripted updates to convert automatically what was possible [2] thus raising the number of translated strings for Japanese on the User Guides from 32 % to 37 %, and my patch for building the Japanese tools we have IMHO done everything we can do.
Or has anybody suggestions for additional things to do now?
If not, I think we're good to publish the new RST User Guides.
So, I propose these next steps: * Get explicit ok by Daisy that we can continue based on her findings * Review and merge patch [3] * Anne decides when to publish User Guides
Andreas
[1]
http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html
[2]
http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001034.html
[3] https://review.openstack.org/162424 -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 _______________________________________________ OpenStack-docs mailing list OpenStack-docs@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
On Thu, Apr 16, 2015 at 4:42 AM, Ying Chun Guo <guoyingc@cn.ibm.com> wrote:
Hello,
There was a meeting with translators in IRC. Andreas Jaeger and Lana Brindley from doc team attended. François Bureau from French team, SungJin Kang from Korean team and myself from Chinese team attended the meeting.
Firstly, Andreas confirmed that the tool chain was extendable. The preprocessing of po/pot before translation could be implemented in tools/generatepot-rst.sh. The postprocessing of po after translation could be done either as part of the building process, or as part of the infra scripts - propose_translation_update_manuals.sh .
Then we talked about how to translate those strings with rst markups. rst markups are more difficult to identified than XML tags. That's why a translators RST cheat sheet is needed. Andreas and Lana explained some markups to translators. At last, all the attendees from translation teams were fine with the rst conversion.
I will continue to maintain the translators cheat sheet. If doc writers introduce new mark ups, don't forget to add to the cheat sheet. The sheet can help the new translators easily understand how to translate.
I think we got the agreement to go on. Many thanks to the attendees.
Wonderful news, thanks to everyone who worked through it together. I love the wiki "cheat sheet" and will be using it myself often. Thank you Olga for identifying additions, please put them on the wiki page for us all to use. For next steps, I'd like to have the RST guide published prior to our last bug day for Kilo. Our remaining tasks are on the wiki page at: https://wiki.openstack.org/wiki/Documentation/Migrate#Publishing_User_Guides Andreas, does the 17th (tomorrow) work for you? These are the remaining steps for publishing: Remove doc/user-guide, doc/user-guide-admin, doc/hot-guide/ directories (ajaeger) Publish new User Guides to proper place (ajaeger) Update entries to index.html pages pointing to new content (annegentle) Update sitemap.xml (annegentle) Add redirects for moved pages removing extra /content/ directory (annegentle) If you see anything is incorrect (or impossible), please let us know. I really need to wrap my head around the redirects now. :) Really appreciate the cross-team collaboration. Thanks, Anne
Best regards Ying Chun Guo (Daisy)
Ying Chun Guo/China/IBM@IBMCN wrote on 2015/04/10 17:04:38:
From: Ying Chun Guo/China/IBM@IBMCN To: Andreas Jaeger <aj@suse.com> Cc: "openstack-i18n@lists.openstack.org" <openstack- i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/04/10 17:09
Subject: Re: [OpenStack-docs] [Openstack-i18n] Status of the RST Documentation Toolchain
Here are my thoughts.
1. I would like the toolchain could be extendable for the future improvement. If we are able to make small and easy improvements before publishing, like handling double stars and double colons (described in [1]), let's do that. In the future, let's continue the improvement. The goal is to provide an easily understandable source strings for translators.
2. I would like the translators to be well educated about the RST markups. I will covert [2] into translators' view. ( I don't think translators would read through this long document to pick out RST markups. ) Clearly list RST markups, give samples, and describe the meanings. Thus the translators could easily understand which words and punctuation characters should not be translated and need to keep them unchanged carefully.
3. Next Thursday, I will have the team meeting with the translators. I will collect their feedback to these RST markups.
@ Andreas and Anne, let me know your feeling tho these thoughts.
Daisy
[1] http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html [2] https://wiki.openstack.org/wiki/Documentation/Markup_conventions
Andreas Jaeger <aj@suse.com> wrote on 2015/04/10 12:38:21:
From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN Cc: "openstack-i18n@lists.openstack.org" <openstack- i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/04/10 12:38 Subject: Re: [OpenStack-docs] [Openstack-i18n] Status of the RST Documentation Toolchain
On 04/09/2015 02:16 PM, Ying Chun Guo wrote:
[...] I investigated the translation process of RST document, asked by Anne and Andreas. While I made test, I used playground-user-guide, which was a quite new document. I didn't pay attention to the pot content changes between the old version and the new version. I'm quite sorry for that. I don't want to block anything. In my mind, the toolchain could be improved continuously, both before publication and after publication.
With the analysis done by Daisy [1] (thanks!) and my scripted updates to convert automatically what was possible [2] thus raising the number of translated strings for Japanese on the User Guides from 32 % to 37 %, and my patch for building the Japanese tools we have IMHO done everything we can do.
Or has anybody suggestions for additional things to do now?
If not, I think we're good to publish the new RST User Guides.
So, I propose these next steps: * Get explicit ok by Daisy that we can continue based on her findings * Review and merge patch [3] * Anne decides when to publish User Guides
Andreas
[1]
http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html
[2]
http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001034.html
[3] https://review.openstack.org/162424 -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 _______________________________________________ OpenStack-docs mailing list OpenStack-docs@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
_______________________________________________ OpenStack-docs mailing list OpenStack-docs@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
-- Anne Gentle annegentle@justwriteclick.com
On 04/16/2015 03:01 PM, Anne Gentle wrote:
On Thu, Apr 16, 2015 at 4:42 AM, Ying Chun Guo <guoyingc@cn.ibm.com <mailto:guoyingc@cn.ibm.com>> wrote:
Hello,
There was a meeting with translators in IRC. Andreas Jaeger and Lana Brindley from doc team attended. François Bureau from French team, SungJin Kang from Korean team and myself from Chinese team attended the meeting.
Firstly, Andreas confirmed that the tool chain was extendable. The preprocessing of po/pot before translation could be implemented in tools/generatepot-rst.sh. The postprocessing of po after translation could be done either as part of the building process, or as part of the infra scripts - propose_translation_update_manuals.sh .
Then we talked about how to translate those strings with rst markups. rst markups are more difficult to identified than XML tags. That's why a translators RST cheat sheet is needed. Andreas and Lana explained some markups to translators. At last, all the attendees from translation teams were fine with the rst conversion.
I will continue to maintain the translators cheat sheet. If doc writers introduce new mark ups, don't forget to add to the cheat sheet. The sheet can help the new translators easily understand how to translate.
I think we got the agreement to go on. Many thanks to the attendees.
Wonderful news, thanks to everyone who worked through it together.
I love the wiki "cheat sheet" and will be using it myself often. Thank you Olga for identifying additions, please put them on the wiki page for us all to use.
For next steps, I'd like to have the RST guide published prior to our last bug day for Kilo.
Our remaining tasks are on the wiki page at: https://wiki.openstack.org/wiki/Documentation/Migrate#Publishing_User_Guides
Andreas, does the 17th (tomorrow) work for you? These are the remaining steps for publishing:
Anne and myself discussed on IRC, here's the plan on what we do tomorrow: * Publishing new content, 6:00 UTC or later, ajaeger will approve and do fixes as needed: Remove entries from .tx/config for guides (ajaeger, done) Remove doc/user-guide, doc/user-guide-admin, doc/hot-guide/ directories (ajaeger) publish new User Guides to proper place (ajaeger) Update entries to index.html pages pointing to new content (annegentle) * Removal of old content, 12:00 UTC or later, annegentle will approve and do fixes as needed: Update sitemap.xml (annegentle) Add redirects for moved pages removing extra /content/ directory (annegentle) Remove old pages from /content/ directory for both user-guide and user-guide-admin on FTP server (annegentle) If anything is missing, tell us! Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
participants (6)
-
Andreas Jaeger
-
Anne Gentle
-
Bernd Bausch
-
Jeremy Stanley
-
Tom Fifield
-
Ying Chun Guo