Material-ui: [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 https://github.com/vuejs/vuejs.org/issues/271#issuecomment-266476746. 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 (https://github.com/mui-org/material-ui/issues/9511#issuecomment-377815552), 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.

[xiaoyu-tamu]

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

[mbrookes]

@earvinLi @medz @xiaoyu-tamu Thanks for your patience - I think we're finally ready for you! https://crowdin.com/project/material-ui-docs

@earvinLi Are you happy to be the owner for Chinese translations?

[earvinLi]

@mbrookes Hi Matt, it's been kind of long. I'm still willing to help but can you ask the other two good fellows if they want to be the owner?

[kbravh]

I can help with any Spanish translation necessary!

[fpudo]

I’m circling back and offering myself again to translate it to Portuguese.

[mbrookes]

@opusartificis @fpudo, thank you. We’re starting with Chinese, but watch this space.

@earvinLi, sure, thanks. Could you translate a page or two to test the processs and let me know how it goes?

[fpudo]

@mbrookes Right on!

[mbrookes]

@earvinLi Please could you ping me on Gitter? (https://gitter.im/mbrookes)

[mbrookes]

@xiaoyu-tamu Thanks for making a start! I have set the top ten based on usage as "high priority" indicated by the up arrow. I have also deprioritised the bottom 10 files, and bottom 3 directories.

Number one (markdown file) is getting-started/installation - we will also, separately, need to translate the home page, but I'll need to code that up first.

Here's the hot-list:

I'm going to push a notification asking for help to translate the docs. Do you think you could come up with a suitable "call to action" in Chinese?

[akaxiaok]

Great! Happy to help with Chinese.

[oliviertassinari]

@akaxiaok You can follow our effort & help us in https://translate.material-ui.com/project/material-ui-docs :).

[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.

[mbrookes]

@fizzvr Traction on Brazilian Portuguese translations has been disappointing to say the least, we might yet abandon it. I don't know about Spanish either - there hasn't been much call for it. I suspect most (European) Spanish speakers are pretty fluent in English.

[fpudo]

@mbrookes Please wait until December 31st to abandon in case we don't move forward with the Brazilian Portuguese translation. It gets very quiet at my
workplace this time of year and I'll have lots of time to work on it.

[oliviertassinari]

@mbrookes @fpudo As far as I know, the Portuguese translation isn't featured anywhere. I don't think that it can work without an edit button as we have for the Chinese :

        if (userLanguage === 'zh') {
          return (
            <Button component="a" href="https://translate.material-ui.com/project/material-ui-docs">
              {'将此页面翻译成中文'}
            </Button>
          );
        }

        return (
          <Button component="a" href={`${sourceCodeRootUrl}${markdownLocation}`}>
            {'Edit this page'}
          </Button>
        );

It would even be better with a banner when the translation is missing.

[mbrookes]

@oliviertassinari what helped initially with Chinese was the notification, but I asked the volunteers on CrowdIn and and here for suggested wording in Portuguese (giving the English translation of the Chinese notification as an example), and got no suggestions.

@fpudo, thanks for offering to work on this when you are less busy. As a priority, please suggest a call to action for the docs notifications, and lets see if we can get things moving!

[el1f]

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

[oliviertassinari]

@mbrookes Notifications won't scale to multiple languages. I propose the following:

1. We move forward with #13765.
2. We add all the languages we eventually want to support.
3. We implement a fallback, if the translation isn't available, we display the English version (1. enables that).
4. We translate the edit button in the languages we support

---

1. If we fallback, we display a nice banner asking for help in the translation. (optional)

[mbrookes]

Notifications won't scale to multiple languages.

Huh? That’s like saying notifications won’t scale to multiple releases.

I’d rather we test the waters with a couple of languages before we turn on the tap for all potential translations. A notification hopefully help kickstart the Portuguese translation effort, as it did for Chinese, then once there is enough content we go live with Portuguese with the localised edit button.

1 / 3 won’t work - like I’ve mentioned in the #13765 discussion, once CrowdIn sync is enabled (permanently or periodically), there won’t be any missing translations.

Other than the code simplification, the fallback PR is redundant.

[oliviertassinari]

Huh? That’s like saying notifications won’t scale to multiple releases.

@mbrookes What I mean by is that the Chinese translation velocity has greatly reduced, I believe it's correlated to the end of the documentation notification usage. While it can kickstart the process, I don't think that it's enough to sustain it. It's why I don't think that it can scale. Also, it's displaying a message to people who have zero interest in the matter. I think that there is a room for improvement.

there won’t be any missing translations.

But we can try to detect it. We can compare the existence and the translation length. If the size between target and source is very similar, then we can conclude that nothing was translated.

[mbrookes]

Your first two comments seem at odds - if removing the notification (why was it removed?) lead to the drop in translation activity, then keeping it would have sustained it. - to the point that Chinese translations would probably now be mostly complete.

That said, I wonder why the button CTA is ineffective?

I agree that if we were to launch multiple translations in parallel (or near so) the current notifications wouldn’t scale.

I wonder if IP geolocation for those would help?

[oliviertassinari]

I believe that the edit button isn't really visible. It's not always clear help is needed. IP geolocation can help.

[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 :).