Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Issues #157

Closed
woodbri opened this issue Jul 15, 2013 · 20 comments
Closed

Documentation Issues #157

woodbri opened this issue Jul 15, 2013 · 20 comments
Milestone

Comments

@woodbri
Copy link
Member

@woodbri woodbri commented Jul 15, 2013

2.4 thought 2.7 have no content yet

Sections 3.1.X seems to be duplicated as 3.2 through 3.11.

@dkastl

This comment has been minimized.

Copy link
Member

@dkastl dkastl commented Jul 16, 2013

I also have started to update the pgRouting workshop and I was planning to copy content from the workshop to the "tutorial". That's why there is nothing yet.

@cvvergara

This comment has been minimized.

Copy link
Member

@cvvergara cvvergara commented Jul 25, 2013

I can do a translation to spanish of the documentation.

@dkastl

This comment has been minimized.

Copy link
Member

@dkastl dkastl commented Jul 25, 2013

@cvvergara Thanks a lot for your offer! For sure translations help a lot of people, who are not so familiar with English. But we must ensure that we don't end up with outdated and not well maintained translations when there are changes to the original. In my opinion an outdated translation is even worse than no translation.

So we should make use of Sphinx capabilities to manage internationalisation of documents: http://sphinx-doc.org/intl.html#intl
It requires a few tweaks to the configuration file and the use of translation tools. Even better would be to use translation services like Transifex then, but I'm not so much familiar with this topic. Do you have some experience with this? Are you interested to elaborate how to create a localisation workflow?

@cvvergara

This comment has been minimized.

Copy link
Member

@cvvergara cvvergara commented Jul 25, 2013

Never used Sphinix before... but I never used postgis nor pgrouting nor mapserver before march this year and I have already a working map of mexico with the 32 states that includes all the 2010 census data, So I am fast learner, I have the time and I would like very much to participate.

@dkastl

This comment has been minimized.

Copy link
Member

@dkastl dkastl commented Jul 26, 2013

That's very kind. I will see if I have the time to configure Sphinx accordingly, so we can manage translations and if it's easy to integrate with online translation services like Transifex, then it would be even easier to use for non-programmers.
I hope this won't be a one-time translation, because I expect that documentation will be extended and updated from time to time.

@cvvergara

This comment has been minimized.

Copy link
Member

@cvvergara cvvergara commented Jul 26, 2013

Have an MC in computer science from Washington University in St. Luis (1995). So programming is not an issue here.

@cvvergara

This comment has been minimized.

Copy link
Member

@cvvergara cvvergara commented Jul 26, 2013

Almost done with reproducing http://pgrouting.org/index.html on sphinix but can you tell me which theme from the built themes from http://sphinx-doc.org/theming.html should I use...
Once I have all the components of the side bar, header and footer working I will start working on how to do the localization of the documentation.

@woodbri

This comment has been minimized.

Copy link
Member Author

@woodbri woodbri commented Jul 26, 2013

We seem to be using theme "haiku", it is defined in doc/CMakeLists.txt at the top of our source tree.

@dkastl

This comment has been minimized.

Copy link
Member

@dkastl dkastl commented Jul 26, 2013

@cvvergara are you building the website or the documentation?
http://docs.pgrouting.org/v2.0.0-rc1/doc/index.html
(also you need to use CMake for the first time you build the documentation, because it generates the configuration file)

I did already some changes to the configuration file to support gettext: 146f116

I want to use Transifex, because it will also allow non-programmers to contribute to translations (I know you're programmer, but we don't want to do everything alone, do we? ;-)

https://www.transifex.com/projects/p/pgrouting/
http://sphinx.readthedocs.org/en/latest/intl.html

On Transifex I created a "pgRouting" project already to be able to see how it works and what we need to provide: https://www.transifex.com/projects/p/pgrouting/

More to come this weekend.

@cvvergara

This comment has been minimized.

Copy link
Member

@cvvergara cvvergara commented Jul 27, 2013

building the website or the documentation? to learn shpinix I am reproducing http://pgrouting.org/index.html
My intention as a start, is to help with the documentation.

last night I started looking at http://sphinx.readthedocs.org/en/latest/intl.html
(no time today because its my son's birthday party.. but tomorrow I will continue with the locale on sphinix and look around on Transifex )

@cvvergara

This comment has been minimized.

Copy link
Member

@cvvergara cvvergara commented Jul 29, 2013

For internationalization using transiflex

Step 4 on http://sphinx.readthedocs.org/en/latest/intl.html#quick-guide suggests that
after creating .pot files with gettext (lines 59 to 66 in CMakeLists.txt) to upload them to
transifex you need to do

$sphinx-intl update-txconfig-resources -p build/locale --transifex-project-name pgrouting
$tx push -s

That way the .po files will be available for translation on transiflex

For internationalization locally (which I am using) (and again after lines 59 to 66)
The following line will create the .po files under build/locale//LC_MESSAGES

sphinx-intl update -c build/doc/_build/conf.py -p build/locale -d build/locale -l es -l ja -l fr -l de

I will start working on the translation to spanish.

requierments
sphinix-intl <--- install using: pip install sphinx-intl
transifex-client <---- install using: pip install transifex-client

@dkastl

This comment has been minimized.

Copy link
Member

@dkastl dkastl commented Jul 30, 2013

Thanks @cvvergara !
I had also build already the .po files. It should be already done with the compile script using CMake, see develop branch.

My questions and concerns are mainly:

  • How do we get the .po to Transifex automatically (should it be automatically?)
  • How do updates in the English master get to Transifex?
  • How do we get the translations from Transifex into http://docs.pgrouting.org (some script would be preferred)
  • How do we prevent that translators get annoyed but steady changes in the English documentation ;-)

And, if you are subscribed to the pgRouting DEV mailing list, then I think it would be better to move the discussion to there, because not many people read the issues.

@dkastl

This comment has been minimized.

Copy link
Member

@dkastl dkastl commented Jul 30, 2013

@cvvergara could you also tell me your name on Transifex so I can add you to the test project there?

@cvvergara

This comment has been minimized.

Copy link
Member

@cvvergara cvvergara commented Jul 30, 2013

signing up to Transifex with cvvergara

how do I subscribe to the pgRouting DEV mailing list?

@cvvergara

This comment has been minimized.

Copy link
Member

@cvvergara cvvergara commented Jul 30, 2013

I also made a friend request on facebook

@dkastl

This comment has been minimized.

Copy link
Member

@dkastl dkastl commented Jul 30, 2013

You find the mailing list links on this page: http://pgrouting.org/development.html

@cvvergara

This comment has been minimized.

Copy link
Member

@cvvergara cvvergara commented Jul 30, 2013

Sent a message using the mailing list, Can you check?

@dkastl

This comment has been minimized.

Copy link
Member

@dkastl dkastl commented Aug 2, 2013

@cvvergara I have the Transifex setup completed and there are 2 scripts now, that should help to get POT files to Transifex and the translations back.

There are several commits related to this and I also modified a bit the documentation structure as I added language code to the path.

I'm not planning to make translations by releases so far. At first people need to translate, then we can see.
Translations are not published automatically to http://docs.pgrouting.org. Again, first some translation needs to happen, then we will see.

So right now there is no need to work with the source code. Translation can be (and should be!) exclusively done in the Transifex project: https://www.transifex.com/projects/p/pgrouting/

@cvvergara

This comment has been minimized.

Copy link
Member

@cvvergara cvvergara commented Aug 3, 2013

Spanish translation 90% done. Tomorrow I will finish. The proof reading I will delay it for next week, so I can detach myself from my own mistakes (proof reading your own work is never good)
http://www.transifex.com/projects/p/pgrouting/language/es/

Can I help with the Japanese version?
there are some lines that are html references so they shouldn't be translated, I can do that.
:)

@dkastl

This comment has been minimized.

Copy link
Member

@dkastl dkastl commented Sep 20, 2013

Let's close this and create a new issue if necessary.

@dkastl dkastl closed this Sep 20, 2013
@dkastl dkastl removed 2.1 labels Mar 23, 2015
cvvergara added a commit that referenced this issue Jul 5, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.