Stream: rustdoc

Topic: Infrastructure for document translation


view this post on Zulip Charles Lew (May 22 2021 at 02:57):

Hello, i'm thinking about doing something inline with https://github.com/rust-lang/community-localization/issues/5 .
Before doing so, i'd like some basic directional review.

view this post on Zulip Joshua Nelson (May 22 2021 at 03:43):

@Charles Lew this is a giant feature, nothing about it is simple

view this post on Zulip Joshua Nelson (May 22 2021 at 03:43):

I would start with an RFC maybe

view this post on Zulip GuillaumeGomez (May 22 2021 at 13:27):

Oh, the translation is back

view this post on Zulip GuillaumeGomez (May 22 2021 at 13:28):

for the translation to be handled by rustdoc, I think we need to be able to generate doc from an external source

view this post on Zulip GuillaumeGomez (May 22 2021 at 13:28):

like a big file which is used as reference for all API entries

view this post on Zulip Charles Lew (May 24 2021 at 05:31):

I decide to try if i can come up with something that works together well with mdbook first. I'll revisit rustdoc part after that.

view this post on Zulip Charles Lew (Jun 06 2021 at 17:28):

Continuing from the topic of https://rust-lang.zulipchat.com/#narrow/stream/226068-t-community.2Fl10n/topic/mdbook.20localization.20.282nd.20try.29 , now we all agree rustdoc should use key-indexed translations. The question is that, if the content itself is not a good enough key (which i was exploring). what could be better?

view this post on Zulip GuillaumeGomez (Jun 07 2021 at 08:44):

I think @Manish Goregaokar meant that the items and not the documentation itself should be used as key (please correct me if I misunderstood). This is something I planned to do, but that will require a LOT of work on rustdoc to allow to have documentation written in files outside the code and then imported back. Funnily enough, I wrote a crate which allows to extract and put back doc comments (from a markdown file) with the rustdoc-stripper crate. However, I really don't recommend it for big projects and certainly not for rustdoc in general.

view this post on Zulip Charles Lew (Jun 07 2021 at 10:28):

thanks!

view this post on Zulip Charles Lew (Jun 07 2021 at 10:32):

I'm also still a little curious what's so bad about using the documentation itself as the key. I've participated in rust annual survey translation for a few times, and we've always been doing this.(Translating paragraph-by-paragraph)

Is it concerns about ambiguities that make people feel bad about it?

view this post on Zulip GuillaumeGomez (Jun 07 2021 at 14:40):

It makes the translation much harder, there is no more "continuity" between paragraphs, and a few more reasons that I don't remember

view this post on Zulip Charles Lew (Jun 07 2021 at 14:52):

Well, taking this as an example. The continuity is still preserved, since neighboring paragraphs are just a few lines away...

view this post on Zulip Manish Goregaokar (Jun 07 2021 at 21:58):

@Charles Lew yeah what @GuillaumeGomez said is correct, I'd say that the doc items should work as keys. So perhaps the path, or something, but annoyingly there's ambiguity when you have reexports and such

view this post on Zulip Manish Goregaokar (Jun 07 2021 at 21:59):

@Charles Lew documentation itself as a key is terrible because the documentation _changes_. the survey works fine because we take great care to _freeze_ the english version before handing it off to translators

view this post on Zulip Manish Goregaokar (Jun 07 2021 at 21:59):

"use the text itself as a key" is an older technique (used by gettext, etc) that has largely been obsoleted

view this post on Zulip Manish Goregaokar (Jun 07 2021 at 22:01):

the way I see rustdoc's thing going is that you have one cli option to export each doc item in rustdoc to a key-value pair, with uniquely named keys, and another cli option that can _take_ all these key-value pairs and "replace" docs

view this post on Zulip Manish Goregaokar (Jun 07 2021 at 22:01):

I'm thinking that we basically have one json or ftl or whatever file per src file, to limit ambiguity, and then the keys are named something sufficiently disambiguating (fully qualified relative path?)

view this post on Zulip Manish Goregaokar (Jun 07 2021 at 22:02):

i'd startt with json or something

view this post on Zulip Manish Goregaokar (Jun 07 2021 at 22:02):

because in the case of rustdoc we don't need fancy i18n features like plurals and stuff, it's pure textual replacement

view this post on Zulip Charles Lew (Jun 08 2021 at 03:42):

Manish Goregaokar said:

"use the text itself as a key" is an older technique (used by gettext, etc) that has largely been obsoleted

Thank you for the insights of this!

view this post on Zulip Charles Lew (Jun 08 2021 at 03:51):

I feel something compatible with markdown parser would be nice. When doing the actual translation it would be nice if the newly written translated markdown doc comments can get a side-preview on-the-fly.

view this post on Zulip GuillaumeGomez (Jun 08 2021 at 08:09):

rustdoc-stripper is compatible with markdown so it's definitely a possibility. And in addition to that, I find markdown simpler to read/edit and you can add comments. But it's personal preference. :)


Last updated: Oct 11 2021 at 22:34 UTC