reactjs / ru.react.dev

React documentation website in Russian / Официальная русская версия сайта React
https://ru.react.dev
Creative Commons Attribution 4.0 International
678 stars 380 forks source link

Стилистические вопросы в новом переводе #851

Open gaearon opened 1 year ago

gaearon commented 1 year ago

Привет.

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

Если есть какие-то похожие моменты, давайте их тут поднимем тоже.

EngiN33R commented 1 year ago

Моё мнение по двум вопросам в начале треда:

dmaykov commented 1 year ago

По поводу пропсов, я думаю можно добавить слово "данные" или "значения", например "Передавать данные через пропсы" или "Передавать значение через пропс"

gaearon commented 1 year ago

У меня больше вопрос именно про герундий. У нас очень много таких страниц с -ing:

и так далее. Идея в том, что каждая страница описывает какой-то один skill или workflow. Так что хотелось бы, чтобы в переводе тоже какая-то общая схема была для этих названий.

Hellnar commented 1 year ago
  1. Не думаю, что обращение на "ты" допустимо в документации. Обращение на "вы" вряд ли кого-то заденет. А на "ты" - может. Поэтому здесь я бы сохранял обращение на "вы".

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

gaearon commented 1 year ago

Какие сейчас самые передовые технические ресурсы на русском? Я давно не смотрел ничего.

Hellnar commented 1 year ago
gaearon commented 1 year ago

Хорошо. Тогда вроде бы есть консенсус:

gaearon commented 1 year ago

Если есть еще стилистические вопросы, которые стоит обсудить, кидайте сюда тоже )

gcor commented 1 year ago

Начал соседнее ишью про перевод слов state и node #849 )

Hellnar commented 1 year ago

Похожая ситуация со словами, как в #849

rainyEra commented 1 year ago

В старой доке мне не нравилось то, что очень сильно сохранялась стилистика оригинального языка. Т.е прямо чувствуется, когда ты читаешь, что как-то не по-русски звучит. Например, "Условный рендеринг" как-то не звучит по-русски. Когда мы читаем, то первая ассоциация к этому слову — условно(не существуя на самом деле), поэтому в самой доке я перевёл так:

Вашим компонентам нужно часто отображать различные вещи в зависимости от различных условий. В React вы можете рендерить JSX в зависимости от его условий

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

gaearon commented 1 year ago

Да, я думаю в целом мы все за то, чтобы язык читался естественно, но не всегда очевидно, как этого достичь ) К примеру, как перевести Conditional Rendering (название страницы)?

rainyEra commented 1 year ago

Да, я думаю в целом мы все за то, чтобы язык читался естественно, но не всегда очевидно, как этого достичь ) К примеру, как перевести Conditional Rendering (название страницы)?

Да, полностью с Вами согласен. Условный рендеринг можно оставить, а в самой доке переводя как-бы пояснять это слово. Я там прикрепил пример "в зависимости от его условий" — звучит гораздо живее, чем каждый раз повторять одно и то же слово. Как-бы чтобы и слишком по-русски не звучало и слишком по-английски.

boldurean commented 1 year ago

Есть некоторые вещи которые надо перевести глобально и замерджить их до перевода страниц. Например, карточки, табы, хлебные крошки (DeepDive - Глубокое погружение, Note - Примечание и т.д)

Сейчас перевожу you may not need an effect, могу попутно перевести вышеперечисленное.

Screenshot 2023-04-26 at 17 16 23 Screenshot 2023-04-26 at 17 16 35
SemyonSR commented 1 year ago

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

boldurean commented 1 year ago

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

Как по мне для веба это довольно распространенное понятие, так как даже в азах изучения CSS есть подобная терминология React начинается с описания "Библиотека для веб - и нативных пользовательских интерфейсов", что само собой подразумевает, что придётся иметь дело с браузерным рендеренгом.

RIP21 commented 1 year ago

Можно использовать словно "отрисовка". Или как минимум уточнить, что под рендерингом подразумевается именно это. Я долго привыкал к этому слову, ибо у меня рендеринг ассоциируется с 3D моделями и моделированием, разработкой игр и пр. но никак не с веб-страницей. Сейчас уже да, но 7 лет назад нет :)

RIP21 commented 1 year ago

По поводу примеров хорошей документации на русском языке, которая не слишком официальная. Думаю ещё можно подать доку. https://doka.guide/ В целом, по части перевода думаю можно так же затегать её редакцию, думаю ребята с радостью помогут прояснить какие-то вопросы и выкристализовать лучшие практики. Вадим Макеев имеет к ней не последнее отношение, а он человек разбирающийся в таких вещах :)

PaulineNemchak commented 1 year ago

Можно использовать словно "отрисовка". Или как минимум уточнить, что под рендерингом подразумевается именно это. Я долго привыкал к этому слову, ибо у меня рендеринг ассоциируется с 3D моделями и моделированием, разработкой игр и пр. но никак не с веб-страницей. Сейчас уже да, но 7 лет назад нет :)

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

RIP21 commented 1 year ago

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

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

Это как я, году на третьем карьеры, наконец перевёл слово void на русский и сразу столько всего стало на свои места и стало в разы очевиднее :) Думаю таких примеров найдётся полно у каждого в этом чатике :)

inoyakaigor commented 1 year ago

Да, я думаю в целом мы все за то, чтобы язык читался естественно, но не всегда очевидно, как этого достичь ) К примеру, как перевести Conditional Rendering (название страницы)?

Отрисовка по условию?

vitalybaev commented 1 year ago

У Веб-стандартов есть давний словарь, как какие-то термины звучат по-русски.

Мне кажется, можно некоторые вещи подсмотреть оттуда

inoyakaigor commented 1 year ago

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

boldurean commented 1 year ago

Да, я думаю в целом мы все за то, чтобы язык читался естественно, но не всегда очевидно, как этого достичь ) К примеру, как перевести Conditional Rendering (название страницы)?

Отрисовка по условию?

А я бы назвал это "Рендеринг в зависимости от условий"

rainyEra commented 1 year ago

Отрисовка по условию?

А я бы назвал это "Рендеринг в зависимости от условий"

Два эти варианта мне нравятся, но я бы всё-таки использовал англицизм "рендеринг", потому что нельзя перевести всё, нужно чем-то жертвовать.

Ну, и касательно таких вариантов перевода - лучше спросить у общества, сделав голосование насчёт различных вариантов. Как вам идея?

Может, Дэн устроит голосование в Твиттере? (если можно)

ghost commented 1 year ago

Я думаю что такие понятия как props,state,hooks и другие react specific понятия лучше оставить на английском без перевода,потому что сложно понять контекст когда видишь в русском тексте переведенные на русский слова которые react specific и дословно даже близко почти никак не переводятся

ntishkevich commented 1 year ago

Я думаю что такие понятия как props,state,hooks и другие react specific понятия лучше оставить на английском без перевода,потому что сложно понять контекст когда видишь в русском тексте переведенные на русский слова которые react specific и дословно даже близко почти никак не переводятся

@kirkhla State и hooks не специфичные только для React. Хуки есть в том же SVN и Git, также есть у всяких сборщиков проектов, как пример, Gradle.

Состояние применяется , в веб-сервисах, в обычных html элементах типа <details> (открыт или закрыт), даже есть паттерн проектирования "Состояние", поэтому это слово не привязано ни к какому UI библиотеке или фреймворку (в Angular и Vue тоже есть функционал по работе с состоянием), это общий термин в CS.

ghost commented 1 year ago

Я знаю и это понятно что такие термины используются не только в React.Просто очень неудобно читать техническую документацию и видеть там «состояние,хуки и всякое такое». Вообще переводить технические термины дословно это считается not a great practice и например даже когда на interviews спрашивают технические вопросы про React/JavaScript.Очень сложно понять что от вас хотят когда говорят «Расскажите про то как работает состояние,замыкание в JavaScript,хуки и тд»😅 Ну а передача пропсов это звучит как cringe

ntishkevich commented 1 year ago

Я знаю и это понятно что такие термины используются не только в React.Просто очень неудобно читать техническую документацию и видеть там «состояние,хуки и всякое такое». Вообще переводить технические термины дословно это считается not a great practice и например даже когда на interviews спрашивают технические вопросы про React/JavaScript.Очень сложно понять что от вас хотят когда говорят «Расскажите про то как работает состояние,замыкание в JavaScript,хуки и тд»😅

Не понимаю вашей проблемы с переводом этих слов. Они точно также являются техническими терминами. Вот например:

Если на интервью у вас хотят узнать как работают замыкания, то интервьюер донесет вам эту мысль используя термин или попытается подвести вас к нему. А если у вас будут спрашивать Closure, вы сразу поймете, что от вас хотят? Может интервьюер хочет узнать о Closure из алгебры или о языке программирования closure.

ghost commented 1 year ago

Ну если интервью по Js/Ts/React/Angular то про алгебру ни разу ещё не спрашивали.Но точно помню что несколько раз не мог ответить на вопросы потому что знал что такое closures,lifting state и другие термины из документации на английском,а что такое Состояние,Замыкание и тд. не знал Я к тому что на мой взгляд при переводе на русский оставить большинство чисто технических терминов на английском или например оформить их как links которые ведут на английскую версию про этот термин

inoyakaigor commented 1 year ago

«Состояние», «замыкание» — это очень часто встречающиеся технические термины

ghost commented 1 year ago

Ну мне только в Российских компаниях когда-то встречались такие термины и звучат они очень странно и не понятно,потому что опять же переводить технические термины дословно на русский наверное все таки не стоит

vitalybaev commented 1 year ago

Ну мне только в Российских компаниях когда-то встречались такие термины и звучат они очень странно и не понятно,потому что опять же переводить технические термины дословно на русский наверное все таки не стоит

Хоть я и любитель англицизмов, перебарщивать с ними не стоит. Как в данном случае быть? Кложура, кложур? Хотя замыкание как по мне вполне себе общеупотребимое и в том же словаре Веб-стандартов тоже имеется, хотя у них нет цели переводить всё, но использовать понятия, которые общеупотребимы в сообществе

Hellnar commented 1 year ago

Задача любого перевода - чтобы целевая аудитория материала понимала, о чем речь. Если мы говорим о том, что термины "рендер", "стейт", "пропсы" - понятные и широко используемые, то речь идет о разработчиках с опытом. Но в этом случае не учитывается опыт новичков, которые эти термины могли никогда не встречать (во многих случаях так и есть).

Первый вариант

Я могу ошибаться, но, насколько я понимаю:

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

И если эквивалента в русском языке нет, использовать транслитерацию. В таком случае мы ориентируемся на новичков, чтобы им было понятнее и они могли быстрее разобраться.

Второй вариант

С другой стороны, в любой профессии существует своя терминология, профессионализмы. Если помимо задачи обучения новичков есть также задача сохранения аутентичности профессии и "втягивание" новичков в эту профессию, то им так или иначе нужно будет разбираться с новыми терминами и использовать их в коде (просто потому, что бОльшая часть всех материалов от статей до библиотек идут только на английском). В этом случае использовать распространенные заимствования и транслитерацию - оправдано. То есть:

Но в этом случае будет много странных слов, которые режут слух, например тот же closure - кложур. Из этой проблемы есть два выхода:

Заключение

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

Поэтому для мейнтейнеров я вижу два решения:

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

Приблизительно так вижу всю ситуацию.

ntishkevich commented 1 year ago

Задача любого перевода - чтобы целевая аудитория материала понимала, о чем речь. Если мы говорим о том, что термины "рендер", "стейт", "пропсы" - понятные и широко используемые, то речь идет о разработчиках с опытом. Но в этом случае не учитывается опыт новичков, которые эти термины могли никогда не встречать (во многих случаях так и есть).

Первый вариант

Я могу ошибаться, но, насколько я понимаю:

  • основная аудитория - разработчики, которые приходят изучать React после JS и часто не имеют представления о том, что такое пропсы, стейты, хуки и т.д.
  • остальная аудитория - разработчики с опытом, которые используют документацию как референс, а не гайд для обучения.

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

  • closure - замыкание, а не кложур
  • state - состояние, а не стейт
  • merge - слияние, а не мёрдж
  • rendering - визуализация/отрисовка, а не рендеринг

И если эквивалента в русском языке нет, использовать транслитерацию. В таком случае мы ориентируемся на новичков, чтобы им было понятнее и они могли быстрее разобраться.

Второй вариант

С другой стороны, в любой профессии существует своя терминология, профессионализмы. Если помимо задачи обучения новичков есть также задача сохранения аутентичности профессии и "втягивание" новичков в эту профессию, то им так или иначе нужно будет разбираться с новыми терминами и использовать их в коде (просто потому, что бОльшая часть всех материалов от статей до библиотек идут только на английском). В этом случае использовать распространенные заимствования и транслитерацию - оправдано. То есть:

  • rendering - рендеринг, а не визуализация
  • state - стейт, а не состояние
  • merge - мёрдж, а не слияние
  • pull request - пул реквест, а не запрос на слияние

Но в этом случае будет много странных слов, которые режут слух, например тот же closure - кложур. Из этой проблемы есть два выхода:

  • Продолжать развивать профессиональную терминологию и вводить в обиход эти странные слова. Изначально многие слова звучали странно. Например для меня таким остается issue - ишью.
  • Делать список исключений. То бишь, сохранять одно правило перевода, но иметь список с исключениями и пополнять их по принципу текущего глоссария.

Заключение

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

  • array - массив (первый вариант)
  • state - состояние (первый вариант)
  • props - пропсы, а не свойства (второй вариант)
  • ref - реф, а не ссылка/отсылка (второй вариант)

Поэтому для мейнтейнеров я вижу два решения:

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

Приблизительно так вижу всю ситуацию.

Если почитать внимательно TRANSLATION.md, то переводы, которые вызывают бурное обсуждение в этом ишью, уже были добавлены.

boldurean commented 1 year ago

@ntishkevich прям с языка снял. Ох уж эти путешественники во времени.

ghost commented 1 year ago

Вообще я думаю что считать новичков аудиторией документации не совсем верно,потому что если человек например прошел курсы Яндекса за 3 месяца или что-то такое то он конечно может себя считать уже Junior,но когда совсем недавно начал работать с framework,(а сейчас многие сразу начинают изучать frameworks,даже без основ Js)то документация покажется очень запутанной и сложной для восприятия новичка @Hellnar

mekarthedev commented 1 year ago

Уточните плиз момент в https://github.com/reactjs/ru.react.dev/blob/main/TRANSLATION.md – там слово "rendering" указано надо переводить как "рендер", без "инг". Но в старой доке, в новых PR, и даже в примерах в TRANSLATION.md повсеместно с "инг".

Это ошибка в TRANSLATION.md?

boldurean commented 1 year ago

Уточните плиз момент в https://github.com/reactjs/ru.react.dev/blob/main/TRANSLATION.md – там слово "rendering" указано надо переводить как "рендер", без "инг". Но в старой доке, в новых PR, и даже в примерах в TRANSLATION.md повсеместно с "инг".

Это ошибка в TRANSLATION.md?

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

mekarthedev commented 1 year ago

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

Так а когда тогда использовать "рендер", а когда "рендеринг"? В TRANSLATION.md слово "render" в каком случае имеется ввиду переводить как "рендер"?

В русском же вроде нет словообразования через "-инг". Производное было бы что-то типа "рендерение".

ntishkevich commented 1 year ago

Уточните плиз момент в https://github.com/reactjs/ru.react.dev/blob/main/TRANSLATION.md – там слово "rendering" указано надо переводить как "рендер", без "инг". Но в старой доке, в новых PR, и даже в примерах в TRANSLATION.md повсеместно с "инг".

Это ошибка в TRANSLATION.md?

@mekarthedev Скорее плохо описанный пример. В TRANSLATION.md идёт перечисление рендер, рендерить, отрендерить, а само английское слово render(ing), вероятно подразумевались производные. Я согласен, что запись сбивает столку. Мы переводили rendering как рендеринг.

mekarthedev commented 1 year ago

@ntishkevich, вопрос по поводу em dash. В оригинальных текстах где-то используется --, который автоматом заменяется на "—", а где-то непосредственно "—". Есть ли какая-то договоренность о том, какой вариант предпочтительнее?

rainyEra commented 1 year ago

Давайте уже как-нибудь решим то, как будет переводить документацию по глоссарию? Нужно решить сейчас, чтобы всё поправить, а новые переводимые документы не редактировались 100 раз.

arturdedela commented 1 year ago

Я вообще не переводчик и впервые взялся что-то перевести, но хочу накинуть в пользу перевода state - стейт, props - пропсы...

У меня "состояние" воспринимается как более абстрактное слово, которое может использоваться много где еще(аналогично со свойствами). А когда видишь/слышишь стейт, то сразу возникает ассоциация с React state/useState/setState. Возможно это не так для тех, кто впервые решил выучить реакт и только открыл документацию. НО, на мой взгляд, погружать людей в слэнг на котором говорят большинство остальных разработчиков - это тоже часть обучения и документации. В разговорах про реакт на кофепоинте ни разу не слышал, чтобы использовали состояние/свойства.

А проблему того, что новички никогда не встречали эти слова можно попробовать решить на первых страницах документации.

А еще прикладываю мнение chatgpt😁

В технической документации React официально используются термины "state" и "props", и эти термины являются частью устоявшейся терминологии React. Хотя переводы "стейт" и "пропсы" также могут быть понятны и использоваться некоторыми разработчиками, использование устоявшихся терминов "state" и "props" может сделать документацию более понятной и доступной для широкой аудитории разработчиков, особенно для тех, кто только начинает изучать React.

ntishkevich commented 1 year ago

@ntishkevich, вопрос по поводу em dash. В оригинальных текстах где-то используется --, который автоматом заменяется на "—", а где-то непосредственно "—". Есть ли какая-то договоренность о том, какой вариант предпочтительнее?

Разницы между ними нет, абсолютно одинаковые. Просто "—" не всегда удается вспомнить как вставить em dash, поэтому быстрее --. Используйте то, что удобнее.

ntishkevich commented 1 year ago

Я вообще не переводчик и впервые взялся что-то перевести, но хочу накинуть в пользу перевода state - стейт, props - пропсы...

У меня "состояние" воспринимается как более абстрактное слово, которое может использоваться много где еще(аналогично со свойствами). А когда видишь/слышишь стейт, то сразу возникает ассоциация с React state/useState/setState. Возможно это не так для тех, кто впервые решил выучить реакт и только открыл документацию. НО, на мой взгляд, погружать людей в слэнг на котором говорят большинство остальных разработчиков - это тоже часть обучения и документации. В разговорах про реакт на кофепоинте ни разу не слышал, чтобы использовали состояние/свойства.

А проблему того, что новички никогда не встречали эти слова можно попробовать решить на первых страницах документации.

А еще прикладываю мнение chatgpt😁

В технической документации React официально используются термины "state" и "props", и эти термины являются частью устоявшейся терминологии React. Хотя переводы "стейт" и "пропсы" также могут быть понятны и использоваться некоторыми разработчиками, использование устоявшихся терминов "state" и "props" может сделать документацию более понятной и доступной для широкой аудитории разработчиков, особенно для тех, кто только начинает изучать React.

Тоже ответ chatGPT:

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

Мне казалось, что вопрос со state как состоянием закрыт... 👀

mekarthedev commented 11 months ago

Нужна помощь! Вот в этом разделе последнее предложение: https://react.dev/reference/react/useEffect#displaying-different-content-on-the-server-and-the-client

In many cases, you can avoid the need for this by conditionally showing different things with CSS.

Я правильно понимаю, что здесь this — это jarring changes, а не pattern, а суть решения в том, чтобы отдельным CSS-ом подогнать размеры элементов initial output под размеры элементов client-only output?