[docs] Translate the docs

[HZooly]

Hey guys, what do you think about documentation translation?

I think it could be nice for v1.

How can it could be done following your current documentation system?

[oliviertassinari]

We would need to start benchmarking how others are handling the issue and copying the best solution. Vue seems to just fork the documentation:

• https://github.com/vuejs-ru/old.ru.vuejs.org
• https://github.com/vuejs/cn.vuejs.org

[mbrookes]

@oliviertassinari But what about API docs?

[oliviertassinari]

what about API docs?

@mbrookes I don't know. It can be done with translation keys. Like api.componentName.propertyName. But this is such an overhead to support i18n.

[mbrookes]

Honestly, I think in a world where the majority of development resources are in English, trying to maintain multiple translations of the docs would be an exercise in futility, and for marginal gain.

[oliviertassinari]

Crowdin is a company that provides translation services. For Open Source projects, Crowdin provides free string translations

https://docusaurus.io/docs/en/translation.html

[HZooly]

Docusaurus could be a nice solution

[oliviertassinari]

@TorzuoliH Docusaurus isn't an option. It's critical for us to dogfood our components.

[le99]

Hi. I’d be willing to help translate the docs to Spanish.

I know that most software documentation is in English, which ideally means every developer should be able to read it. But this is not the case. When there is no “official” documentation in one's own language, what takes its place are blogs, videos, etc. with rather questionable authority: just look at the suggested resources to learn React in Spanish: https://github.com/jlobos/react-espanol . I believe that having the docs in several languages can make Material-UI much more approachable.

[andreacornaglia]

Happy to help with any Spanish/Portuguese translations if needed as well!

[oliviertassinari]

Looking at our market share in China, I think that we really need to push the translation story of Material-UI forward. For instance, we have less traffic from China than from France…

[oliviertassinari]

I have started benchmarking what the industry is doing. Some solutions to look at that are interesting from an architectural point of view:

• Vue. They use Hexo under the hood but I believe they aren't using the i18n feature of the library.
  Their workflow is explained in French translation vuejs/v2.vuejs.org#271 (comment). It's encouraging the community to fork the documentation and to do the translation on their side. For instance, vuejs-fr/vuejs.org, vuejs-ru/vuejs.org.
  This is the solution that requires the less work on our side. However, I find it inefficient. It's also the approach used by Bootstrap.
• Nuxt is using a variety of tools to do so. Hopefully, for us, there are some details :). I think that it worth trying GitLocalize out.
• Jest is using Docusaurus to build the documentation. They also use crowdin to translate the documentation. I believe crowdin is a competitor to GitLocalize. It's also something to try out.

Also: https://www.transifex.com

[mbrookes]

It's encouraging the community to fork the documentation and to do the translation on their side. [...] I find it inefficient.

I agree - I started to write a comment before you submitted yours, to the effect that whatever we do, change tracking needs to be automated. Otherwise there's no simple way for translation contributors to keep up to date with changes, and no way for users of the translated docs to know which parts may be out-of-date.

Ideally a user could hover over text flagged as out-of-date text to see the up-to-date English original, and perhaps even submit an updated translation in context. Similarly, for newly added text, it would display the English, and allow translations to be submitted inline.

I have to assume there's something available to support this, as it's the only practical solution to keeping multiple translations of a living document up-to-date, while allowing users to see the original in context... We just have to find it :-)

[raftario]

I'd be happy to help with French translation if needed.

[earvinLi]

Chinese here! Also working for Hai... More than willing to help with Chinese doc.

[fpudo]

I can help with Portuguese translation.

[JKodev]

My main language is Spanish, I can help with translation.

[medz]

@oliviertassinari material-ui is very popular with developers in China, but many companies do not like it. Because it uses React! I come from China. I started using material-ui from the 0.x version. I like him very much. By the way, my friends also like material-ui. If necessary, I would like to contribute my ability to convert documents into Chinese. But I currently see the official document structure is not conducive to fork modified to other languages!

[oliviertassinari]

Looking at the traffic origin on GitHub, I think that we should only be focusing on English and Chinese to start with.

https://www.similarweb.com/website/github.com

I have been benchmarking the approach used by Bootstrap. They relly on the community to do it. The Chinese versions have around 10% of the global traffic. It's not too bad.

@medz Thanks for the feedback. Yes, we would need to work on the core documentation structure.
One important challenge is to stay up to date. What process should we use?
I have seen some website relying on Google Translate… but people don't need us to use Google Translate.

[medz]

@oliviertassinari The i18n structure or the directory structure of the language package is all good, or the structure that can provide the fork modification language is also a good choice, but the structure of the fork modification language needs a new domain name to be deployed. From the perspective of user use, the i18n language Package structure or directory structure is a better choice.

[medz]

If there are Chinese documents, material-ui will be more popular in China. To reveal a small fact, many English developers in China are very bad. Seeing English there is an urge to give up, my English ability is also very bad, I believe there are a lot of grammar problems in my reply!

[medz]

😄Sorry, I understand what you mean by mistake. What you mean is to keep the documentation in other languages up-to-date. I saw that Docusaurus used the Crowdin for translation after using the i18n structure to generate files. I experienced a very unusual version of Crowdin's translation! According to docusaurus, Crowdin can provide free translation support for open source projects. In this way, translators only need to join in submitting translations to the document. Crowdin automatically identifies the parts that need to be updated based on the build of the warehouse file.

Thanks.

[fizzvr]

Honestly, I think in a world where the majority of development resources are in English, trying to maintain multiple translations of the docs would be an exercise in futility, and for marginal gain.

Sound's good!

[fpudo]

@oliviertassinari I understand you, but in my opinion the reason why other countries aren't using it, it's because it's in English. I'm pretty sure that with a Portuguese version of it, per example, brazilians would use it more in their projects.

[mbrookes]

@fizzvr

trying to maintain multiple translations of the docs would be an exercise in futility

Sound's good!

Perhaps a better choice of words would have been "trying to manually maintain", otherwise changes to the source material might be missed in the translations, or the translations might be supplemented with content not included in the source (or other) languages.

I subsequently described an idealised solution (#9511 (comment)), and it does seem that there are third party services that attempt to deliver on this.

We need to find one that can be integrated in the the Material-UI docs site and structure without a massive overhaul, but which also provides sufficient utility to make it worthwhile.

@fpudo If we can find the right solution, the the number of languages is only limited by the will of people to take on the translation effort.

[michael-land]

I'd be happy to help with Chinese translation. @ me is needed. :)

[marsonmao]

Hi, is there a way to turn off the auto-translate of the mui website? I'd like to view the original English documentation but don't know how to do it.

[oliviertassinari]

Hi, is there a way to turn off the auto-translate of the mui website? I'd like to view the original English documentation but don't know how to do it.

@mbrookes Might have to move forward with the subfolder approach if we want to support this use case out side of the box. @marsonmao adding ?lang=en was supposed to work 🤔, otherwise, you have to change the accepted languages of your browser :/.

[marsonmao]

@oliviertassinari Hmm tried url like this and not working: https://material-ui.com/demos/chips/?lang=en, also tried changing the language setting of my Chrome browser and not working either. I now open the doc website using my IE edge lol.

It's just that, shouldn't this translate function be manually controlled? I'm not sure if everyone wants to view the documentation in their native language all the time? For myself I read English doc most of the time since it's more consistent with the source code. I read Chiese docs only when I need a quick learn of something new. So I think a manual switch is a more reasonable approach?

[oliviertassinari]

@marsonmao We went with the simplest possible solution to get it working, end-to-end. It's feedback like this one that we can leverage for improving the docs. Yes, I agree.

[marsonmao]

@oliviertassinari Great, then hope I can use it in the future. I'll use IE to open the doc for a work-around 😄 Also thanks for the work of material ui!

[mbrookes]

@marsonmao - @oliviertassinari is correct. If as you say, your preference is to read websites in English, you need to change your browser language preferences. I have tested it again with Firefox, Safari and Chrome, and it is working as expected.

In the future we might add the option to override the language preference set in the browser, but for now, use the browser settings.

[caiobessa]

I can help with any Portuguese translate. Most of the entry-level and middle-level developers in Brazil are not interesting in study English.

[mbrookes]

@andreacornaglia @fpudo @caiobessa Thanks for offering to help. Brazilian Portuguese translation is now live!

[nicolasiensen]

Hey, I can also help with the Portuguese translation. I'm just wondering how the process of translating strings in Crowdin looks like? Who approves the translations, and who should create the pull request with the new translations, the reviewer or the author?

[nicolasiensen]

Sorry! I just realized that we have a bot that pushes the translation changes to the repository, so I guess that, after being approved, the translations are automagically included on a new pull request for review, correct?

[oliviertassinari]

@nicolasiensen Correct! Thank you for giving it a shot with the first page :).

[fpudo]

I’ll start translating tomorrow!!! Super cool!

[mbrookes]

If someone could please suggest some wording for a notification in Portuguese, I'll add it to the docs.

For Chinese, I suggested "Help translate the Material-UI documentation into Chinese", the translation came back as "Help Material-UI translate the documentation into Chinese", so anything along those lines would be good. Feel free to be creative – whatever you think will bring in the most help.

[mbrookes]

Also, here are a few tips to make translating easier:

• The copy button is your friend! Use it to copy the source text with formatting before translating any text.
• Don't literally translate project names, such as Material-UI, React etc.
• Do translate comments and rendered strings (such as button labels) in code samples.
• Don't translate component names such as "Button". (It's fine to translate it when it refers to the generic object, for example: "you can use a button"; or "Buttons" as a heading referring to buttons in general.)
• Check out the keyboard shortcuts, they'll save you some time. (Keyboard icon on the right of the app bar when in the editor.) They can be customised to your liking.
• Invite as many people as you can to work with you on it. It's a big job!
• If something doesn't seem to be working right, let us know. There are lots of settings we can tweak.

If you are a proofreader, please don't approve your own translations, other than the those that are copied directly from the source such as demo objects, for example {{"demo": "pages/demos/app-bar/SimpleAppBar.js"}} which should be copied untranslated using the copy button, so can be approved immediately.

[caiobessa]

@mbrookes thanks :)

[fizzvr]

@mbrookes tranlations to Portuguese are similiar to spanish a "little". Some people could help with spanish translations. I included.

[el1f]

Dunno if this is the place but if you were to look for help with the italian translation I could lend a hand

[mbrookes]

For anyone interested in helping with translations, French, German, Spanish, Russian and Japanese are now live (alongside Chinese and Portuguese):

https://translate.material-ui.com/

[oliviertassinari]

We can close the issue now: https://next.material-ui.com/discover-more/languages/. Thank you everybody for the help & the contributions! We have done the majority of the infrastructure work. We now need an ongoing effort to keep the translations up-to-date :).