Translations

[howiezhao]

This is a great community, I can help translate this site into Chinese, how do i start?

[janbrohl]

I would assume translation could be done using sphinx-intl but I have not tried it.

I would gladly help with a German translation.

[plaindocs]

Translating the site would be a huge task for any individual! Do either of you have ideas on where you'd like to start?

http://www.writethedocs.org/guide/ probably makes sense, but even then there is a lot of content.

I'm happy to do some work around setting up both languages for translation if you're still interested in this.

[janbrohl]

I am.

[howiezhao]

@plaindocs This is a good idea, I plan to start translating from the guide.

[plaindocs]

Hey, I got caught up in stuff - I'll try to test out intl in a week or so.

[howiezhao]

@plaindocs OK

[plaindocs]

Hi @janbrohl how familar are you with sphinx-intl?

We're using a datatemplate extension which doesn't seem to play nice with sphinx-intl.
Not sure how easy it would be to just grab a subset of the docs (the Guide) and translate those?

[janbrohl]

I have read https://www.sphinx-doc.org/en/master/usage/advanced/intl.html only.

If you are using sphinxcontrib.datatemplates - I am a maintainer of that package. Please open an issue there as we have not looked into compatibility there at all yet.

(Forgot to mention earlier: I'd start translation on the guide, too.)

[plaindocs]

We're using a fork of that (was needed to add some functionality that might well now be available) so I'll need to test that out as well.

[Stolzenhain]

If you are using sphinxcontrib.datatemplates - I am a maintainer of that package. Please open an issue there as we have not looked into compatibility there at all yet.

(Forgot to mention earlier: I'd start translation on the guide, too.)

We could start producing translation drafts somewhere till the buidl setup is sorted out.

@janbrohl Two quick question concerning contribution from your experience:

1. Any advice on structrual conventions we need to respect while creating .rst files in different languages? Do we simply add an extension to the filename?
2. By what measure are we tracking document changes happening –after– the initial translation? Are we referencing commit IDs or is there an automatic way of – say – tracking changes newer than the referenced translation?

[janbrohl]

1. I don't know about structural conventions. Sphinx does insert language-based pieces of text in the generated html so I would suggest creating technically separate folders or branches with a conf.py each and link via Intersphinx. This would also enable us using localized paths/filenames. For gettext based translation there would only be a locales directory containing translations for pieces of text plus some config.
   There may be different conventions on text structuring in different languages/cultures but for german, a sentence by sentence translation would normally not feel off. On the tech side it is important to have UTF encoded rst files for translations.
2. For a gettext-based aproach, I suppose there should be warnings for untranslated blocks of text when changing only the english version, so this way, tracking the english version with all translations would be simple but also required for a correct full build. (For exact, up-to-date translations the gettext appoach seems better.)
   For the separated approach: If the different versions don't need to be very direct translations we would see some natural drift needing a bit of synchronization work but offering more freedom for improvements.
   I don't know of any existing solutions to this tracking-problem but an option for tracking would be to add a file for each translation (eg. translation-targets.yml) stating which page aims for which version like

de/docs/guide/loslegen.rst:
  target: en/docs/guide/starting.rst
  target-version: 1.2.3
  target-commit: abcdef
  target-tag: en1.2.3
# Only one of target-version, target-commit, target-tag of course.

then, a implementing a tool tracking changes should not be too complex.
Actually, I think referring to tags would be best but seems not supported with clickabe links by Github.
Btw. the version/release field in conf.py is currently unused.

Language setting:

www/docs/conf.py

Line 82 in d9fe5cd

language = 'en'

[Stolzenhain]

Wow, thanks for answering so fast – the separate metadata approach looks robust enough. Let's see, if I can pull off a pull request anytime soon.

[silopolis]

Hello friends,

May I ask what is the status of this more than two years after last post ?
I'd gladly initiate/participate in the French translation :)

TY
J