search

mui / material-ui

Material UI: Ready-to-use foundational React components, free forever. It includes Material UI, which implements Google's Material Design.
https://mui.com/material-ui/
MIT License
91.86k stars 31.57k forks source link

[docs] Translate the docs #9511

Closed HZooly closed 5 years ago

HZooly commented 6 years ago

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

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

mbrookes commented 6 years ago

@oliviertassinari But what about API docs?

oliviertassinari commented 6 years ago

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

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

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

Docusaurus could be a nice solution

oliviertassinari commented 6 years ago

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

le99 commented 6 years ago

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

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

oliviertassinari commented 6 years ago

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

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

Also: https://www.transifex.com

mbrookes commented 6 years ago

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

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

earvinLi commented 6 years ago

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

fpudo commented 5 years ago

I can help with Portuguese translation.

JKodev commented 5 years ago

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

medz commented 5 years ago

@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 commented 5 years ago

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

capture d ecran 2018-06-13 a 00 30 42 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 commented 5 years ago

@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 commented 5 years ago

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

😄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 commented 5 years ago

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

@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 commented 5 years ago

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

michael-land commented 5 years ago

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

mbrookes commented 5 years ago

@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 commented 5 years ago

@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 commented 5 years ago

I can help with any Spanish translation necessary!

fpudo commented 5 years ago

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

mbrookes commented 5 years ago

@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 commented 5 years ago

@mbrookes Right on!

mbrookes commented 5 years ago

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

mbrookes commented 5 years ago

@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:

image

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

Great! Happy to help with Chinese.

oliviertassinari commented 5 years ago

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

marsonmao commented 5 years ago

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

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

@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 commented 5 years ago

@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 commented 5 years ago

@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 commented 5 years ago

@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 commented 5 years ago

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

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

nicolasiensen commented 5 years ago

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

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

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

fpudo commented 5 years ago

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

mbrookes commented 5 years ago

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

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

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

@mbrookes thanks :)