(In case it wasn't obvious, English is not my native language.) In my experience, while UI string or book translation efforts work, translation efforts of over-time-edited non-UI text or collections of text fail to maintain a status where anyone but the most committed-to-monolingualism-on-principle reader benefits from hiding content based on the current language choice. The EU puts massive resources into maintaining multilingual Web sites and still can't make it work the way people idealize it would work.
Yet, people like to think that they can do it, so you can't count on there being a warning about admitting failure. (Sinatra does have such warnings and, indeed, some of the READMEs are stale.)
For README-length things, when there are two languages, I think that just showing both gives the reader the best idea with the least link-following effort.
I suggest designing for the monolingual and bilingual cases where what the languages are is ad hoc instead of either designing for the case where a crate has as many README translations as Sinatra does or designing for the case where the user expects to see documentation only in $lang.
Anecdote, but I've seen the reverse said, so: as a reader of English there's several projects made by chinese people that are entirely documented in chinese, a language I cannot read, which I use. There are sections of industries where this is common, and indeed if I stuck to projects I could read the docs of without translating there are areas I could not work with at all. Supporting more than English seems to me less like a fancy or a waste of time and more like acknowledging and supporting and even improving how things already are.
Having powerful tools to support processes for empowering communities from
lesser-used and under-resourced languages is critical to the goal of enabling
collaboration between individuals. As projects grow it seems natural that some
standards and practices around robust and useful internationalization would be
developed and evolved.
I view internationalization as being at the heart of both the social and
technical aspects of a project. Social in the sense that it empowers
communication and technical in its inevitable integration of tools and some
degree of involvement of the core developers in communicating their work to the
broadest audience possible.
Translation work, specifically the level to which Rust is translated, should be
viewed as incremental and increasing with both need and the proper tools and
other resources.
This is open to re-interpretation but we might outline and rank the following in
terms of both importance as well as implementation complexity, these levels
might be prioritized as some yet to be determined relationship between
importance and difficulty
General Categories:
core Rust crates and tools
default installation documentation and command line prompts requiring human
interaction
material not used directly during a standard installation but which
supports a default build
other core documentation including major tooling
material indirectly related to installation and tooling
crates used during installation not maintained as part of core Rust
Specifically the implementation complexity should start with looking at the
documents which can be automatically translated and regenerated reflecting
revisions. This means integrating a consistent translation task as part of the
current updating and addition of documents and code.
One hurdle seems to involve how selection of a default and making switching to
translated versions convenient is exposed to the user. Sharding the ecosystem
and tooling into localized reflections of varying quality doesn't seem ideal
especially if higher tier translations might need to be reviewed during the
release cycle adding additional finalization criteria.
There are two discussions going on in parallel and I think it would help to distinguish them.
Should crate authors/the standard library/rustc translate documentation and error messages?
Should there be a way to mark the primary language of existing documentation?
Note that 1. is asking for more work from the authors of the crate, while 2. is asking for a feature from the tools used with the crate. A lot of the people saying "there's no point because the English documentation will always be more up-to-date/easier to search" are talking about 1, which was not the original request.
No, that's not exactly what's being discussed. Crate authors don't need to translate their docs, this can be done separately by contributors. Ideally, enabling contributors to translate the docs should involve very little effort for the crate authors.
Furthermore, if rustdoc gains internationalization capabilities, nobody is required to use them. They will be used by the standard library, and maybe by very popular crates that have the bandwidth to provide high quality translations, and by some crates whose primary language is not English.
There's no need to translate every single crate into 10 different languages.
Please note that there are other scenarios other than having only one single README in Chinese
README is in Chinese but they have a separate English translated version, this is due to the fact that Chinese documentation gets updated first. Someone showed me https://crates.io/crates/nature
(there is also translated Chinese README but those works well now so ignored here)
So I believe we should have an option to allow setting the language of README.md. But so far I haven't seen any README only in Chinese. Someone showed me https://crates.io/crates/dcli
Also, searching crates.io with Chinese characters doesn't seemed to get anything (even if the character appears in the description). Try https://crates.io/search?q=拼音
@kornel If you want to ask in the respective communities
If any, Chinese (Cantonese) is my mothertongue but I don't know most of the technical terms in Chinese so reading English docs will still be easier for me but if there's a translation I might read it too.