Translating RST source with Sphinx builds
Hi all, We're preparing to migrate user guides to RST to improve ease of authoring for documentation. The spec [1] is now published, and we've got a research item for a toolchain that can "slice" RST similar to the DocBook slicing we do now. Reading the Sphinx documentation, it seems that you can run sphinx-build -b get-text to extract translatable strings to get a collection of .po files. This seems very similar to our current docbook slicing script. Does anyone have time this release to go through the RST files we're creating with the Sphinx workflow and analyze the results? I don't intend to publish the RST-based user guides until we have agreement on the translation toolchain, so we have until April 9, but ideally we'll have answers this month -- originally on the spec I wanted answers by last month, but without a lot of complex RST to test there wasn't a great way to research. Now that we are getting more RST files in openstack/openstack-manuals/doc/playground-user-guide [3] I would appreciate help here. Thanks, Anne 1. http://specs.openstack.org/openstack/docs-specs/specs/kilo/migrate-to-new-we... 2. http://sphinx-doc.org/latest/intl.html
Anne, I would take a look at this new format, and see how it could fit to our translation process. Thank you for postpone the publish till the agreement on translation toolchain. Best regards Ying Chun Guo (Daisy) From: Anne Gentle <annegentle@justwriteclick.com> To: "openstack-i18n@lists.openstack.org" <openstack-i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/02/02 22:06 Subject: [Openstack-i18n] Translating RST source with Sphinx builds Hi all, We're preparing to migrate user guides to RST to improve ease of authoring for documentation. The spec [1] is now published, and we've got a research item for a toolchain that can "slice" RST similar to the DocBook slicing we do now. Reading the Sphinx documentation, it seems that you can run sphinx-build -b get-text to extract translatable strings to get a collection of .po files. This seems very similar to our current docbook slicing script. Does anyone have time this release to go through the RST files we're creating with the Sphinx workflow and analyze the results? I don't intend to publish the RST-based user guides until we have agreement on the translation toolchain, so we have until April 9, but ideally we'll have answers this month -- originally on the spec I wanted answers by last month, but without a lot of complex RST to test there wasn't a great way to research. Now that we are getting more RST files in openstack/openstack-manuals/doc/playground-user-guide [3] I would appreciate help here. Thanks, Anne 1. http://specs.openstack.org/openstack/docs-specs/specs/kilo/migrate-to-new-we... 2. http://sphinx-doc.org/latest/intl.html _______________________________________________ Openstack-i18n mailing list Openstack-i18n@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
On 02/03/2015 03:22 PM, Ying Chun Guo wrote:
Anne,
I would take a look at this new format, and see how it could fit to our translation process.
Daisy, I did a little playing around and want to share what I did: 1) To build the pot files: $ sphinx-build -b gettext doc/playground-user-guide/source/ doc/playground-user-guide/locale/ This creates a file per directory or top-level file. 2) so, next i run "msgcat *.pot > playground-user-guide.pot" to create a single pot file 3) I would upload the pot file 4) We can download it again 5) And then it's running msgmerge to merge the content back to the multiple files. We really should have only one file per book - otherwise we get duplicated "index.pot" files from each book and have multiple books in a repo. I haven't had time to test all of this together properly and then create some simple script. If you can tell me how to do it properly, I can help with enhancing the infra scripts so that this is done automatically - but I'm also happy to review any patches and answer questions ;) Thanks 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
Hello, I met with problem to build html documents. There are many opinions to set. I want to understand how you would build English HTML document. Then I could follow the similar steps to build translated document. Any links sharing with me? Best regards Ying Chun Guo (Daisy) From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN, Anne Gentle <annegentle@justwriteclick.com> Cc: "openstack-i18n@lists.openstack.org" <openstack-i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/02/04 04:02 Subject: Re: [OpenStack-docs] [Openstack-i18n] Translating RST source with Sphinx builds On 02/03/2015 03:22 PM, Ying Chun Guo wrote:
Anne,
I would take a look at this new format, and see how it could fit to our translation process.
Daisy, I did a little playing around and want to share what I did: 1) To build the pot files: $ sphinx-build -b gettext doc/playground-user-guide/source/ doc/playground-user-guide/locale/ This creates a file per directory or top-level file. 2) so, next i run "msgcat *.pot > playground-user-guide.pot" to create a single pot file 3) I would upload the pot file 4) We can download it again 5) And then it's running msgmerge to merge the content back to the multiple files. We really should have only one file per book - otherwise we get duplicated "index.pot" files from each book and have multiple books in a repo. I haven't had time to test all of this together properly and then create some simple script. If you can tell me how to do it properly, I can help with enhancing the infra scripts so that this is done automatically - but I'm also happy to review any patches and answer questions ;) Thanks 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
Hi Daisy, Once this merges: https://review.openstack.org/#/c/152690/ You can run tox -e docs to see the Html output. Maybe you can test that patch to make sure it works for you? I've got full instructions here that I tested on Mac and Laurel tested on Windows: https://wiki.openstack.org/wiki/Documentation/Migrate Let us know if you have trouble. Anne Gentle Content Stacker anne@openstack.org
On Feb 5, 2015, at 5:17 PM, Ying Chun Guo <guoyingc@cn.ibm.com> wrote:
Hello,
I met with problem to build html documents. There are many opinions to set. I want to understand how you would build English HTML document. Then I could follow the similar steps to build translated document.
Any links sharing with me?
Best regards Ying Chun Guo (Daisy)
<graycol.gif>Andreas Jaeger ---2015/02/04 04:02:34---On 02/03/2015 03:22 PM, Ying Chun Guo wrote: > Anne,
From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN, Anne Gentle <annegentle@justwriteclick.com> Cc: "openstack-i18n@lists.openstack.org" <openstack-i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/02/04 04:02 Subject: Re: [OpenStack-docs] [Openstack-i18n] Translating RST source with Sphinx builds
On 02/03/2015 03:22 PM, Ying Chun Guo wrote:
Anne,
I would take a look at this new format, and see how it could fit to our translation process.
Daisy,
I did a little playing around and want to share what I did:
1) To build the pot files:
$ sphinx-build -b gettext doc/playground-user-guide/source/ doc/playground-user-guide/locale/
This creates a file per directory or top-level file.
2) so, next i run "msgcat *.pot > playground-user-guide.pot" to create a single pot file
3) I would upload the pot file
4) We can download it again
5) And then it's running msgmerge to merge the content back to the multiple files.
We really should have only one file per book - otherwise we get duplicated "index.pot" files from each book and have multiple books in a repo.
I haven't had time to test all of this together properly and then create some simple script. If you can tell me how to do it properly, I can help with enhancing the infra scripts so that this is done automatically - but I'm also happy to review any patches and answer questions ;)
Thanks 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
Thanks, Anne. I finally generate HTML pages in English and in Chinese. Do we want to use the same command (i.e. tox) to build different language documents? I use "sphinx-build -D language='zh_CN'" to generate Chinese document. If we want to use tox to build translated documents, tox.ini needs to be modified a little. Best regards Ying Chun Guo (Daisy) Anne Gentle <annegentle@justwriteclick.com> wrote on 2015/02/06 07:29:45:
From: Anne Gentle <annegentle@justwriteclick.com> To: Ying Chun Guo/China/IBM@IBMCN Cc: Andreas Jaeger <aj@suse.com>, "openstack- docs@lists.openstack.org" <openstack-docs@lists.openstack.org>, "openstack-i18n@lists.openstack.org" <openstack-i18n@lists.openstack.org> Date: 2015/02/06 07:30 Subject: Re: [OpenStack-docs] [Openstack-i18n] Translating RST source with Sphinx builds
Hi Daisy,
Once this merges:
https://review.openstack.org/#/c/152690/
You can run tox -e docs to see the Html output. Maybe you can test that patch to make sure it works for you?
I've got full instructions here that I tested on Mac and Laurel tested on Windows:
https://wiki.openstack.org/wiki/Documentation/Migrate
Let us know if you have trouble.
Anne Gentle Content Stacker anne@openstack.org
On Feb 5, 2015, at 5:17 PM, Ying Chun Guo <guoyingc@cn.ibm.com> wrote:
Hello,
I met with problem to build html documents. There are many opinions to set. I want to understand how you would build English HTML document. Then I could follow the similar steps to build translated document.
Any links sharing with me?
Best regards Ying Chun Guo (Daisy)
<graycol.gif>Andreas Jaeger ---2015/02/04 04:02:34---On 02/03/2015 03:22 PM, Ying Chun Guo wrote: > Anne,
, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/02/04 04:02 Subject: Re: [OpenStack-docs] [Openstack-i18n] Translating RST
From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN, Anne Gentle <annegentle@justwriteclick.com> Cc: "openstack-i18n@lists.openstack.org" <openstack-i18n@lists.openstack.org source with Sphinx builds
On 02/03/2015 03:22 PM, Ying Chun Guo wrote:
Anne,
I would take a look at this new format, and see how it could fit to our translation process.
Daisy,
I did a little playing around and want to share what I did:
1) To build the pot files:
$ sphinx-build -b gettext doc/playground-user-guide/source/ doc/playground-user-guide/locale/
This creates a file per directory or top-level file.
2) so, next i run "msgcat *.pot > playground-user-guide.pot" to create a single pot file
3) I would upload the pot file
4) We can download it again
5) And then it's running msgmerge to merge the content back to the multiple files.
We really should have only one file per book - otherwise we get duplicated "index.pot" files from each book and have multiple books in a repo.
I haven't had time to test all of this together properly and then create some simple script. If you can tell me how to do it properly, I can help with enhancing the infra scripts so that this is done automatically - but I'm also happy to review any patches and answer questions ;)
Thanks 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
On 02/06/2015 08:30 AM, Ying Chun Guo wrote:
Thanks, Anne. I finally generate HTML pages in English and in Chinese.
Do we want to use the same command (i.e. tox) to build different language documents? I use "sphinx-build -D language='zh_CN'" to generate Chinese document. If we want to use tox to build translated documents, tox.ini needs to be modified a little.
We currently use tox to build translated documents and should continue doing so. For Docbook, we use doc-tools-check-languages.conf. I suggest to create a new script - or enhance the existing one - that gets called from tox.ini and uses doc-tools-check-languages.conf to configure which books and which languages to build, Andreas
Best regards Ying Chun Guo (Daisy)
Anne Gentle <annegentle@justwriteclick.com> wrote on 2015/02/06 07:29:45:
From: Anne Gentle <annegentle@justwriteclick.com> To: Ying Chun Guo/China/IBM@IBMCN Cc: Andreas Jaeger <aj@suse.com>, "openstack- docs@lists.openstack.org" <openstack-docs@lists.openstack.org>, "openstack-i18n@lists.openstack.org" <openstack-i18n@lists.openstack.org> Date: 2015/02/06 07:30 Subject: Re: [OpenStack-docs] [Openstack-i18n] Translating RST source with Sphinx builds
Hi Daisy,
Once this merges:
https://review.openstack.org/#/c/152690/
You can run tox -e docs to see the Html output. Maybe you can test that patch to make sure it works for you?
I've got full instructions here that I tested on Mac and Laurel tested on Windows:
https://wiki.openstack.org/wiki/Documentation/Migrate
Let us know if you have trouble.
Anne Gentle Content Stacker anne@openstack.org
On Feb 5, 2015, at 5:17 PM, Ying Chun Guo <guoyingc@cn.ibm.com> wrote:
Hello,
I met with problem to build html documents. There are many opinions to set. I want to understand how you would build English HTML document. Then I could follow the similar steps to build translated document.
Any links sharing with me?
Best regards Ying Chun Guo (Daisy)
<graycol.gif>Andreas Jaeger ---2015/02/04 04:02:34---On 02/03/2015 03:22 PM, Ying Chun Guo wrote: > Anne,
, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/02/04 04:02 Subject: Re: [OpenStack-docs] [Openstack-i18n] Translating RST
From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN, Anne Gentle <annegentle@justwriteclick.com> Cc: "openstack-i18n@lists.openstack.org" <openstack-i18n@lists.openstack.org source with Sphinx builds
On 02/03/2015 03:22 PM, Ying Chun Guo wrote:
Anne,
I would take a look at this new format, and see how it could fit to our translation process.
Daisy,
I did a little playing around and want to share what I did:
1) To build the pot files:
$ sphinx-build -b gettext doc/playground-user-guide/source/ doc/playground-user-guide/locale/
This creates a file per directory or top-level file.
2) so, next i run "msgcat *.pot > playground-user-guide.pot" to create a single pot file
3) I would upload the pot file
4) We can download it again
5) And then it's running msgmerge to merge the content back to the multiple files.
We really should have only one file per book - otherwise we get duplicated "index.pot" files from each book and have multiple books in a repo.
I haven't had time to test all of this together properly and then create some simple script. If you can tell me how to do it properly, I can help with enhancing the infra scripts so that this is done automatically - but I'm also happy to review any patches and answer questions ;)
Thanks 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
_______________________________________________ Openstack-i18n mailing list Openstack-i18n@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
-- 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
Thanks to Daisy's experimentation and great documentation on https://wiki.openstack.org/wiki/I18n/Tools, we've updated the infra scripts and the setup in openstack-manuals so that translation of RST files can start now. Uploading of the files to transifex is working now and I expect that the import from transifex works as well. Next is building a localized guide. The script is ready and I just build a Japanese playground-user-guide document (script at https://review.openstack.org/162424) The change needs some minor integration work before we can merge it - and then we need translated manuals. Translators, don't translate the playground-user-guide manual, this is just our test environement. Once it's ready, we'll tell you. Looking at the translation side of RST souce, I'm happy now, the big hurdle is done. 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
Thank you Andreas. I just want to remind you that building networking-guide might meet with errors, because this book contains two kinds of source files. There is an existing networking-guide.pot under locale folder now. Building RST source would generate another networking-guide.pot in the same folder, which might cause the error. This book might need a special care. I don't understand why the book has two types of source files. Do we have plan to change them into 1 format ? Best regards Ying Chun Guo (Daisy) Andreas Jaeger <aj@suse.com> wrote on 2015/03/10 15:57:41:
From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN, Anne Gentle <annegentle@justwriteclick.com> Cc: "openstack-i18n@lists.openstack.org" <openstack- i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/03/10 15:57 Subject: Re: [OpenStack-docs] [Openstack-i18n] Translating RST source with Sphinx builds
Thanks to Daisy's experimentation and great documentation on https://wiki.openstack.org/wiki/I18n/Tools, we've updated the infra scripts and the setup in openstack-manuals so that translation of RST files can start now.
Uploading of the files to transifex is working now and I expect that the import from transifex works as well.
Next is building a localized guide. The script is ready and I just build a Japanese playground-user-guide document (script at https://review.openstack.org/162424)
The change needs some minor integration work before we can merge it - and then we need translated manuals.
Translators, don't translate the playground-user-guide manual, this is just our test environement. Once it's ready, we'll tell you.
Looking at the translation side of RST souce, I'm happy now, the big hurdle is done.
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
On 03/10/2015 09:11 AM, Ying Chun Guo wrote:
Thank you Andreas.
I just want to remind you that building networking-guide might meet with errors, because this book contains two kinds of source files. There is an existing networking-guide.pot under locale folder now. Building RST source would generate another networking-guide.pot in the same folder, which might cause the error. This book might need a special care.
I don't understand why the book has two types of source files. Do we have plan to change them into 1 format ?
The book is currently transitioned from XML to RST - and they choose to use the same directory instead of a temporary one like we do with the user guide. Yes, this needs special treatment. And please do NOT translate the guide yet, it is massively changing, Andreas
Best regards Ying Chun Guo (Daisy)
Andreas Jaeger <aj@suse.com> wrote on 2015/03/10 15:57:41:
From: Andreas Jaeger <aj@suse.com> To: Ying Chun Guo/China/IBM@IBMCN, Anne Gentle <annegentle@justwriteclick.com> Cc: "openstack-i18n@lists.openstack.org" <openstack- i18n@lists.openstack.org>, "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> Date: 2015/03/10 15:57 Subject: Re: [OpenStack-docs] [Openstack-i18n] Translating RST source with Sphinx builds
Thanks to Daisy's experimentation and great documentation on https://wiki.openstack.org/wiki/I18n/Tools, we've updated the infra scripts and the setup in openstack-manuals so that translation of RST files can start now.
Uploading of the files to transifex is working now and I expect that the import from transifex works as well.
Next is building a localized guide. The script is ready and I just build a Japanese playground-user-guide document (script at https://review.openstack.org/162424)
The change needs some minor integration work before we can merge it - and then we need translated manuals.
Translators, don't translate the playground-user-guide manual, this is just our test environement. Once it's ready, we'll tell you.
Looking at the translation side of RST souce, I'm happy now, the big hurdle is done.
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
-- 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 (3)
-
Andreas Jaeger
-
Anne Gentle
-
Ying Chun Guo