Translations - Githubissues

howiezhao commented 4 years ago

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

janbrohl commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

I am.

howiezhao commented 4 years ago

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

plaindocs commented 4 years ago

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

howiezhao commented 4 years ago

@plaindocs OK

plaindocs commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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:

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?
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 commented 4 years ago

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.
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: https://github.com/writethedocs/www/blob/d9fe5cda013332d4f0657693e6d7110569021e88/docs/conf.py#L82

Stolzenhain commented 4 years ago

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 commented 1 year ago

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

sootynemm commented 1 year ago

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

Likewise!

silopolis commented 1 year ago

Le ven. 11 nov. 2022 à 15:39, sootynemm @.***> a écrit :

Likewise!

Meaning French ?

sootynemm commented 1 year ago

Le ven. 11 nov. 2022 à 15:39, sootynemm @.***> a écrit : Likewise! Meaning French ?

Yes, although I am not francophone, I can work with a native French speaker in collaboration if that helps. Pour le vérifier après, c'est tout :)

silopolis commented 1 year ago

Le ven. 11 nov. 2022 à 18:28, sootynemm @.***> a écrit :

Yes, although I am not francophone, I can work with a native French speaker in collaboration if that helps. Pour le vérifier après, c'est tout :)

Excellent ! :)

plaindocs commented 1 year ago

Hi folks. This never got off the ground in the previous incarnation.

If anyone is familiar enough with translation sphinx to get a branch started I'll do what I can to get it merged. Definitely avoid anything in conf/* though.

sootynemm commented 1 year ago

as a former translator just learning to code, is there anything... easier to comprehend... than this documentation here? translation is hard enough as it is, but i have no idea where to locate the pootle: https://www.sphinx-doc.org/en/master/usage/advanced/intl.html#quick-guide

plaindocs commented 1 year ago

heh, sorry about that @sootynemm - I don't have a bunch of experience with that either. I'm trying to get the Call for Proposals launched, but I'll try to have a look after that.

I think this is where you want to be looking

Stolzenhain commented 1 year ago

easier to comprehend

You're right – starting the actual translation is more important than perfecting a setup currently.

That's why I proposed placing the file anywhere as a starting point, create a pull request and make up the config later on. I never got to it though, sorry.

sootynemm commented 1 year ago

totally. well, i'll see what i can tackle this weekend i suppose! thanks :)

Stolzenhain commented 1 year ago

gave it a try, see #1849

sootynemm commented 1 year ago

see https://github.com/sootynemm/writethedocs_guide_fr/tree/main/docs/guide

this is the first pass of the french prose;

we could set up a kanban with any francophone volunteers that wanna compare the translation with the source and edit where they see fit;

not sure what localization protocol would be preferred for URLs so leaving as-is for now;

silopolis commented 1 year ago

Le dim. 20 nov. 2022 à 23:34, sootynemm @.***> a écrit :

see https://github.com/sootynemm/writethedocs_guide_fr/tree/main/docs/guide

this is the first pass of the french prose;

This is awesome to see someone else jumping on this!

Nevertheless, I think this may be going too fast and that we should first select a toolchain and put it in place before taking the risk of wasting to much energy, and building a maintenance and synchronization nightmare.

We, LinuxCNC docs and translation team, had a very bad time setting this up afterward and resyncing existing translations to import them into the proper workflow.

As we have the chance that Sphinx has i18n built-in (which wasn't our case with AsciiDoc), and unless there is a real blocker, we should actually discuss how this should be setup.

Are there issues impeding use of sphinx-intl to setup a gettext based toolchain with a nice and helpful translation platform like Crowdin, Weblate or Transifex?

not sure what localization protocol would be preferred for URLs so leaving

as-is for now;

This is also among the questions that should be answered beforehand if it has the potential to badly impact accumulated translation work later.

Stolzenhain commented 1 year ago

Nevertheless, I think this may be going too fast and that we should first select a toolchain and put it in place before taking the risk of wasting to much energy, and building a maintenance and synchronization nightmare. […] as-is for now; This is also among the questions that should be answered beforehand if it has the potential to badly impact accumulated translation work later.

Hello – seeing that this has been lingering for some time, I'd support @janbrohl 's comment:

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 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 […] then, implementing a tool tracking changes should not be too complex.

Which strikes me as sensible.

My question: Are these the next steps? Who would take on one of them?

including the intersphinx module in a translation branch
agreeing on a folder structure
agreeing on a config structure
running test builds against the new structure
and probably targeting the translating branch/tag w/ our pull requests

plaindocs commented 1 year ago

Hey folks,

Thanks for looking into this, and getting started!

We really do need some tooling behind this, otherwise there is no way of knowing what changes when the English page changes, which will be no fun for everyone.

It would be great if someone who has run translation with sphinx-intl before could look at this, and see what the technical side is. But if nobody else jumps on that I'll have a look "within some timeframe".

silopolis commented 1 year ago

Le lun. 21 nov. 2022 à 17:07, Plaindocs @.***> a écrit :

It would be great if someone who has run translation with sphinx-intl before could look at this, and see what the technical side is. But if nobody else jumps on that I'll have a look "within some timeframe".

I have no experience with this but as I'm translating Sphinx to french ATM, and I'm interested in learning that feature for other projects in my backlog. I'd gladly give it a try... Of course, any kind of advise, direction or mentoring will be gratefully welcome :)

Maybe I can do this tomorrow...

silopolis commented 1 year ago

Hi,

First things first, best wishes to yall for the coming year. May yall be healthy and safe :)

Sorry guys, end of year was a mess (aren't they all ?!) :/ I may be able to bend over this in the next days...

sootynemm commented 1 year ago

Happy new year. Let me know if I can pitch in in any way, even just as a fresh pair of eyes!

silopolis commented 1 year ago

Thanks, it will certainly be of great help! I'll fork and create a branch for this with a PR linked to this issue.

One thing that may be nice to discuss the target translation platform. Proposed contenders would be:

Weblate for a truly Open Source solution (https://github.com/WeblateOrg)
Crowdin for best UX and more
Transifex

All three have free hosted plans for Open Source projects. Once sphinx-intl is configured and POT files generated, test setups could be configured to support platform choice...

Stolzenhain commented 1 year ago

One thing that may be nice to discuss the target translation platform.

I understood that due to the few updates one wouldn't aim for update-sensitive variants but simply a mirrored folder structure w/ a separate config. Seeing that few of the pages receive update commits, one could simply check the file history diff.

As for grammar comments / corrections, couldn't these be continued to be handled in pull requests?

[Edit:] Looks like I misunderstood the package approach as I don't get why one would need a POT-based workflow here.

silopolis commented 1 year ago

Number of updates is one thing, number of languages is another. Translation platforms offer nice, featured and user friendly UIs to translators, whatever their technical level. Having the luck of being a Sphinx-based project with built-in support for translation and not using it would be a pity. Further, considering the purpose of the project, not using the best tool and practice for the job wouldn't make sense.

At least, I know that for French I'll use sphinx-intl and one of the platforms above, even if it to push translated files here in the end...

writethedocs / www

Translations #1155