Material-ui: [документы] Перевести документы

Нам нужно начать сравнивать, как другие решают проблему, и копировать лучшее решение. Vue, кажется, просто разветвляет документацию:

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

@oliviertassinari А как насчет документов API?

как насчет документов API?

@mbrookes Я не знаю. Это можно сделать с помощью ключей перевода. Как api.componentName.propertyName . Но это такие накладные расходы на поддержку i18n.

Честно говоря, я думаю, что в мире, где большинство ресурсов разработки находится на английском языке, попытка поддерживать несколько переводов документации была бы бесполезной и незначительной выгодой.

Crowdin — компания, предоставляющая услуги перевода. Для проектов с открытым исходным кодом Crowdin предоставляет бесплатные переводы строк.

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

Docusaurus может быть хорошим решением

@TorzuoliH Докузавр не вариант. Для нас очень важно проверить наши компоненты.

Привет. Я был бы готов помочь перевести документы на испанский язык.

Я знаю, что большая часть документации по программному обеспечению написана на английском языке, что в идеале означает, что каждый разработчик должен уметь ее читать. Но это не так. Когда нет «официальной» документации на родном языке, ее место занимают блоги, видео и т. д. с довольно сомнительным авторитетом: просто посмотрите предлагаемые ресурсы для изучения React на испанском языке: https://github.com/jlobos / реагировать-эспанол . Я считаю, что наличие документации на нескольких языках может сделать Material-UI гораздо более доступным.

Будем рады помочь с любым испанским/португальским переводом, если это необходимо!

Глядя на нашу долю рынка в Китае, я думаю, что нам действительно нужно продвигать историю перевода Material-UI. Например, у нас меньше трафика из Китая, чем из Франции…

Я начал проводить бенчмаркинг того, что делает отрасль. Некоторые решения, на которые стоит обратить внимание, интересны с архитектурной точки зрения:

• Вью . Они используют Hexo под капотом, но я считаю, что они не используют функцию библиотеки i18n .
  Их рабочий процесс объясняется в https://github.com/vuejs/vuejs.org/issues/271#issuecomment -266476746. Это поощряет сообщество разветвлять документацию и выполнять перевод на своей стороне. Например, vuejs-fr/vuejs.org , vuejs-ru/vuejs.org .
  Это решение, которое требует меньше усилий с нашей стороны. Однако я считаю его неэффективным. Это также подход, используемый Bootstrap.
• Nuxt использует для этого множество инструментов . Надеюсь, для нас есть какие-то подробности :). Я думаю, что стоит попробовать GitLocalize .
• Jest использует Docusaurus для создания документации. Они также используют crowdin для перевода документации. Я считаю, что crowdin является конкурентом GitLocalize. Это также то, что нужно попробовать.

Также: https://www.transifex.com

Это поощряет сообщество разветвлять документацию и выполнять перевод на своей стороне. [...] Я считаю это неэффективным.

Я согласен - я начал писать комментарий до того, как вы отправили свой, о том, что что бы мы ни делали, отслеживание изменений должно быть автоматизировано. В противном случае у участников перевода не будет простого способа быть в курсе изменений, а пользователи переведенных документов не смогут узнать, какие части могут быть устаревшими.

В идеале пользователь мог бы навести указатель мыши на текст, помеченный как устаревший, чтобы увидеть обновленный оригинал на английском языке и, возможно, даже отправить обновленный перевод в контексте. Точно так же для недавно добавленного текста он будет отображать английский язык и позволит отправлять переводы как встроенные.

Я должен предположить, что есть что-то доступное для поддержки этого, поскольку это единственное практическое решение для поддержания нескольких переводов живого документа в актуальном состоянии, позволяя пользователям видеть оригинал в контексте... Нам просто нужно его найти: -)

Я был бы рад помочь с французским переводом, если это необходимо.

Китайцы сюда! Также работаю в Hai... Более чем готов помочь с китайским документом.

Могу помочь с португальским переводом.

Мой основной язык испанский, могу помочь с переводом.

@oliviertassinari material-ui очень популярен среди разработчиков в Китае, но многим компаниям он не нравится. Потому что он использует React! Я из Китая. Я начал использовать material-ui с версии 0.x. Мне он очень нравится. Кстати, моим друзьям тоже нравится material-ui. Если необходимо, я хотел бы внести свою способность конвертировать документы на китайский язык. Но в настоящее время я вижу, что официальная структура документа не способствует вилке, модифицированной для других языков!

Глядя на происхождение трафика на GitHub, я думаю, что для начала нам следует сосредоточиться только на английском и китайском языках.

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

Я тестировал подход, используемый Bootstrap . Они полагаются на сообщество, чтобы сделать это. На китайские версии приходится около 10% мирового трафика. Это не так уж плохо.

@medz Спасибо за отзыв. Да, нам нужно будет поработать над структурой основной документации.
Одна из важных задач — оставаться в курсе событий. Какой процесс мы должны использовать?
Я видел какой-то веб-сайт, использующий Google Translate… но людям не нужно, чтобы мы использовали Google Translate.

@oliviertassinari Структура i18n или структура каталогов языкового пакета хороши, или структура, которая может предоставить язык модификации форка, также является хорошим выбором, но структура языка модификации форка требует развертывания нового доменного имени. С точки зрения использования пользователем структура пакета или структура каталогов языка i18n является лучшим выбором.

Если будут китайские документы, то material-ui будет популярнее в Китае. Чтобы раскрыть небольшой факт, многие английские разработчики в Китае очень плохи. Увидев английский, хочется сдаться, мои знания английского тоже очень плохи, я считаю, что в моем ответе много грамматических проблем!

😄Извините, я понимаю, что вы имеете в виду под ошибкой. Что вы имеете в виду, так это поддерживать документацию на других языках в актуальном состоянии. Я видел, что Docusaurus использовал Crowdin для перевода после использования структуры i18n для создания файлов. Я столкнулся с очень необычной версией перевода Краудина! Согласно docusaurus, Crowdin может предоставить бесплатную поддержку перевода для проектов с открытым исходным кодом. Таким образом, переводчикам нужно только присоединиться к отправке переводов к документу. Crowdin автоматически определяет части, которые необходимо обновить, на основе сборки файла хранилища.

Спасибо.

Честно говоря, я думаю, что в мире, где большинство ресурсов разработки находится на английском языке, попытка поддерживать несколько переводов документации была бы бесполезной и незначительной выгодой.

Звучит отлично!

@oliviertassinari Я вас понимаю, но, на мой взгляд, причина, по которой другие страны не используют его, в том, что он на английском языке. Я почти уверен, что с португальской версией, например, бразильцы будут больше использовать ее в своих проектах.

@физзвр

попытка поддерживать несколько переводов документов была бы бесполезным упражнением

Звучит отлично!

Возможно, лучшим выбором слов было бы «пытаться поддерживать вручную », иначе изменения в исходном материале могли быть пропущены в переводах или переводы могли быть дополнены содержанием, не включенным в исходный (или другой) язык.

Впоследствии я описал идеализированное решение (https://github.com/mui-org/material-ui/issues/9511#issuecomment-377815552), и похоже, что есть сторонние сервисы, которые пытаются реализовать это.

Нам нужно найти тот, который можно интегрировать в сайт и структуру документации Material-UI без капитального ремонта, но который также обеспечивает достаточную полезность, чтобы сделать его стоящим.

@fpudo Если мы сможем найти правильное решение, количество языков ограничено только желанием людей взять на себя усилия по переводу.

Буду рад помочь с китайским переводом. @ мне нужен. :)

@earvinLi @medz @xiaoyu-tamu Спасибо за ваше терпение - я думаю, что мы наконец-то готовы принять вас! https://crowdin.com/project/material-ui-docs

@earvinLi Вы счастливы быть владельцем китайских переводов?

@mbrookes Привет, Мэтт, это было довольно давно. Я все еще готов помочь, но не могли бы вы спросить двух других хороших парней, хотят ли они быть владельцами?

Я могу помочь с любым испанским переводом!

Я возвращаюсь назад и снова предлагаю себя перевести на португальский.

@opusartificis @fpudo , спасибо. Мы начинаем с китайского, но следите за этим пространством.

@earvinLi , конечно, спасибо. Не могли бы вы перевести страницу или две, чтобы протестировать процессы и сообщить мне, как они идут?

@mbrookes Давай !

@earvinLi Пожалуйста, не могли бы вы пропинговать меня на Gitter? (https://gitter.im/mbrookes)

@xiaoyu-tamu Спасибо за начало! Я установил первую десятку на основе использования как «высокий приоритет», обозначенный стрелкой вверх. Я также лишил приоритета нижние 10 файлов и нижние 3 каталога.

Номер один (файл уценки) — это getting-started/installation — нам также отдельно нужно будет перевести домашнюю страницу, но сначала мне нужно ее закодировать.

Вот горячий список:

Я собираюсь отправить уведомление с просьбой о помощи в переводе документов. Как вы думаете, вы могли бы придумать подходящий «призыв к действию» на китайском языке?

Здорово! Рад помочь с китайским.

@akaxiaok Вы можете следить за нашими усилиями и помогать нам в https://translate.material-ui.com/project/material-ui-docs :).

Привет, есть ли способ отключить автоперевод сайта mui? Я хотел бы просмотреть оригинальную документацию на английском языке, но не знаю, как это сделать.

Привет, есть ли способ отключить автоперевод сайта mui? Я хотел бы просмотреть оригинальную документацию на английском языке, но не знаю, как это сделать.

@mbrookes Возможно , нам придется продвинуться вперед с подходом к подпапкам, если мы хотим поддерживать этот вариант использования из коробки. @marsonmao добавление ?lang=en должно было сработать 🤔, в противном случае вам придется изменить поддерживаемые языки вашего браузера :/.

@oliviertassinari Хм, попробовал такой URL и не работает: https://material-ui.com/demos/chips/?lang=en , также пытался изменить языковые настройки моего браузера Chrome, но тоже не работает. Теперь я открываю веб-сайт с документацией, используя свой IE edge, лол.

Просто, разве эта функция перевода не должна управляться вручную? Я не уверен, что все хотят постоянно просматривать документацию на своем родном языке? Лично я большую часть времени читаю англоязычную документацию, так как она больше соответствует исходному коду. Я читаю документы Chiese только тогда, когда мне нужно быстро узнать что-то новое. Так что я думаю, что ручной переключатель является более разумным подходом?

@marsonmao Мы выбрали самое простое решение, чтобы заставить его работать от начала до конца. Подобные отзывы мы можем использовать для улучшения документации. Да, я согласен.

@oliviertassinari Отлично, тогда надеюсь, что смогу использовать его в будущем. Я буду использовать IE, чтобы открыть документ для обхода 😄 Также спасибо за работу material ui!

@marsonmao - @oliviertassinari прав. Если, как вы говорите, вы предпочитаете читать веб-сайты на английском языке, вам необходимо изменить языковые настройки браузера. Я снова протестировал его с Firefox, Safari и Chrome, и он работает так, как ожидалось.

В будущем мы можем добавить возможность переопределять языковые настройки, установленные в браузере, но пока используйте настройки браузера.

Я могу помочь с любым португальским переводом. Большинство разработчиков начального и среднего уровня в Бразилии не заинтересованы в изучении английского языка.

@andreacornaglia @fpudo @caiobessa Спасибо, что предложили помощь. Бразильский португальский перевод теперь доступен !

Эй, я также могу помочь с переводом на португальский язык. Мне просто интересно, как выглядит процесс перевода строк в Crowdin? Кто утверждает переводы и кто должен создавать пул-реквест с новыми переводами — рецензент или автор?

Прости! Я только что понял, что у нас есть бот, который отправляет изменения перевода в репозиторий, поэтому я предполагаю, что после утверждения переводы автоматически включаются в новый запрос на проверку, верно?

@nicolasiensen Верно! Спасибо, что попробовали первую страницу :).

Завтра начну перевод!!! Очень круто!

Если кто-то может предложить формулировку уведомления на португальском языке, я добавлю ее в документы.

Для китайского я предложил «Помогите перевести документацию Material-UI на китайский язык», перевод вернулся как «Помогите Material-UI перевести документацию на китайский язык», так что все в этом духе было бы хорошо. Не стесняйтесь проявлять творческий подход — все, что, по вашему мнению, принесет наибольшую пользу.

Кроме того, вот несколько советов, которые облегчат перевод:

• Кнопка копирования — ваш друг! Используйте его для копирования исходного текста с форматированием перед переводом любого текста.
• Не переводите названия проектов буквально, например, Material-UI, React и т. д.
• Переводите комментарии и отображаемые строки (например, метки кнопок) в примерах кода.
• Не переводите имена компонентов, такие как «Кнопка». (Можно перевести его, когда он относится к общему объекту, например: «Вы можете использовать кнопку» или «Кнопки» как заголовок, относящийся к кнопкам в целом.)
• Ознакомьтесь с сочетаниями клавиш, они сэкономят вам время. (Значок клавиатуры справа от панели приложения в редакторе.) Их можно настроить по своему вкусу.
• Пригласите как можно больше людей для работы над ним. Это большая работа!
• Если вам кажется, что что-то работает не так, сообщите нам об этом. Есть много настроек, которые мы можем настроить.

Если вы являетесь корректором, пожалуйста, не одобряйте свои собственные переводы, за исключением тех, которые скопированы непосредственно из источника, таких как демонстрационные объекты, например, {{"demo": "pages/demos/app-bar/SimpleAppBar.js"}} , которые должны быть скопированы без перевода с помощью кнопки копирования, поэтому могут быть одобрены немедленно.

@mbrookes спасибо :)

Перевод @mbrookes на португальский язык похож на испанский «немного». Некоторые люди могли бы помочь с испанским переводом. Я включен.

@fizzvr Traction на бразильских португальских переводах, мягко говоря, разочаровывает, мы могли бы еще отказаться от него. Испанский я тоже не знаю - особого спроса на него не было. Я подозреваю, что большинство (европейцев) носителей испанского языка довольно свободно говорят по-английски.

@mbrookes Пожалуйста, подождите до 31 декабря, чтобы отказаться, если мы не продвинемся вперед с переводом на бразильский португальский язык. у меня становится очень тихо
рабочее место в это время года, и у меня будет много времени, чтобы поработать над ним.

@mbrookes @fpudo Насколько я знаю, португальский перевод нигде не используется. Я не думаю, что это может работать без кнопки редактирования, как у нас для китайцев:

        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>
        );

Лучше бы даже с баннером, когда перевод отсутствует.

@oliviertassinari изначально помогло с китайским уведомлением, но я попросил добровольцев на CrowdIn и здесь предложить формулировку на португальском языке (приведя в качестве примера английский перевод китайского уведомления), и не получил никаких предложений.

@fpudo , спасибо, что предложили поработать над этим, когда вы менее заняты. В качестве приоритета, пожалуйста, предложите призыв к действию для уведомлений о документах, и давайте посмотрим, сможем ли мы сдвинуть дело с мертвой точки!

Не знаю, то ли это место, но если бы вы искали помощи с итальянским переводом, я мог бы протянуть руку

Уведомления @mbrookes не масштабируются на несколько языков. Я предлагаю следующее:

1. Мы продвигаемся вперед с # 13765.
2. Мы добавляем все языки, которые в конечном итоге хотим поддерживать.
3. Мы реализуем запасной вариант, если перевод недоступен, мы показываем английскую версию (1. включает это).
4. Мы переводим кнопку редактирования на поддерживаемые языки

1. Если мы отступаем, мы показываем красивый баннер с просьбой о помощи в переводе. (по желанию)

Уведомления не масштабируются на несколько языков.

Хм? Это все равно, что сказать, что уведомления не будут масштабироваться на несколько выпусков.

Я бы предпочел, чтобы мы попробовали воду с парой языков, прежде чем мы откроем кран для всех потенциальных переводов. Мы надеемся, что уведомление поможет начать работу по переводу на португальский язык, как это было с китайским, а затем, когда будет достаточно контента, мы перейдем к португальскому языку с локализованной кнопкой редактирования.

1/3 не будет работать — как я упоминал в обсуждении #13765, после включения синхронизации CrowdIn (постоянно или периодически) не будет отсутствующих переводов.

Помимо упрощения кода, резервный PR является избыточным.

Хм? Это все равно, что сказать, что уведомления не будут масштабироваться на несколько выпусков.

@mbrookes Я имею в виду, что скорость китайского перевода значительно снизилась, я полагаю, что это связано с прекращением использования уведомлений о документации. Хотя это может дать толчок процессу, я не думаю, что этого достаточно для его поддержания. Вот почему я не думаю, что он может масштабироваться. Кроме того, он отображает сообщение для людей, которые не заинтересованы в этом вопросе. Я думаю, что есть возможности для улучшения.

не будет отсутствующих переводов.

Но мы можем попытаться обнаружить его. Мы можем сравнить существование и длину перевода. Если размер между целевым и исходным текстом очень похож, то мы можем сделать вывод, что ничего не было переведено.

Ваши первые два комментария кажутся противоречащими друг другу: если удаление уведомления (почему оно было удалено?) привело к падению переводческой активности, то сохранение его поддержало бы его. - до такой степени, что китайские переводы, вероятно, теперь будут в основном завершены.

Тем не менее, мне интересно, почему кнопка CTA неэффективна?

Я согласен, что если бы мы запускали несколько переводов параллельно (или почти так), текущие уведомления не масштабировались бы.

Интересно, поможет ли IP-геолокация для них?

Я считаю, что кнопка редактирования на самом деле не видна. Не всегда понятно, нужна ли помощь. IP-геолокация может помочь.

Для всех, кто хочет помочь с переводами, теперь доступны французский, немецкий, испанский, русский и японский языки (наряду с китайским и португальским):

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

Теперь мы можем закрыть вопрос: https://next.material-ui.com/discover-more/languages/. Спасибо всем за помощь и вклад! Мы выполнили большую часть работ по инфраструктуре. Теперь нам нужны постоянные усилия, чтобы поддерживать переводы в актуальном состоянии :).