Merge pull request #61 from reactjs/another-guy/style-guide

Translate "style-guide.md"

Author: lex111

TRANSLATION.md

@@ -4,6 +4,18 @@
 
 Пожалуйста, используйте этот ишью, если вы хотите что-то перевести и узнать.
 
+## Оглавление
+
+* [Перевод на русский язык сайта reactjs.org](#Перевод-на-русский-язык-сайта-reactjsorg)
+  * [Оглавление](#Оглавление)
+  * [Общие правила](#Общие-правила)
+    * [Слово живое и мёртвое](#Слово-живое-и-мёртвое)
+  * [Универсальное руководство по стилю](#Универсальное-руководство-по-стилю)
+    * [Идентификаторы заголовков](#Идентификаторы-заголовков)
+    * [Текст в блоках кода](#Текст-в-блоках-кода)
+    * [Внешние ссылки](#Внешние-ссылки)
+  * [Соглашение по переводу (глоссарий)](#Соглашение-по-переводу-глоссарий)
+
 ## Общие правила
 
 - _Вы_ и его производные пишите с маленькой буквы
@@ -17,7 +29,7 @@
 - Исключайте отсылки на пол читателя (см. секцию 3 на [этой странице](http://www.un.org/ru/gender-inclusive-language/guidelines.shtml))
 - Названия статей и заголовки пишутся с одной заглавной буквы («Компоненты и пропсы», не «Компоненты и Пропсы»).
 
-## Слово живое и мёртвое
+### Слово живое и мёртвое
 
 Прежде чем переводить, почитайте пару страниц из «Слова живого и мёртвого» Норы Галь. Хотя бы эти две:
 
@@ -49,7 +61,107 @@
 
 Небольшие вольности в переводе допускаются, но только если они помогают передать смысл. Перевод не должен быть ни деревянным, ни фамильярным. Истина где-то посередине.
 
-## Соглашение по переводу
+## Универсальное руководство по стилю
+
+Описанные ниже правила пришли [из репозитория](https://github.com/reactjs/reactjs.org-translation/blob/master/style-guide.md), предписывающего стиль общий для **всех** языков, на которые переводится документация.
+
+### Идентификаторы заголовков
+
+Каждый заголовок имеет явный идентификатор:
+
+```md
+## Try React {#try-react}
+```
+
+**НЕ** переводите такие идентификаторы! Они используются для навигации. Изменение идентификатора неизбежно приведёт к поломке, если на документ ссылкаются извне, например так:
+
+```md
+Прочтите [главу для начинающих](/getting-started#try-react), чтобы узнать больше.
+```
+
+✅ Можно:
+
+```md
+## Попробуйте React {#try-react}
+```
+
+❌ НЕЛЬЗЯ:
+
+```md
+## Попробуйте React {#попробуйте-react}
+```
+
+Это сломает ссылку, приведённую в примере выше.
+
+### Текст в блоках кода
+
+Не переводите текст в блоках кода, кроме комментариев. А вот комментарии и текст в строках следует переводить, если они не относятся к коду.
+
+Пример:
+```js
+// Example
+const element = <h1>Hello, world</h1>;
+ReactDOM.render(element, document.getElementById('root'));
+```
+
+✅ МОЖНО:
+
+```js
+// Пример
+const element = <h1>Hello, world</h1>;
+ReactDOM.render(element, document.getElementById('root'));
+```
+
+✅ ТОЖЕ МОЖНО:
+
+```js
+// Пример
+const element = <h1>Здравствуй, мир!</h1>;
+ReactDOM.render(element, document.getElementById('root'));
+```
+
+❌ НЕЛЬЗЯ:
+
+```js
+// Пример
+const element = <h1>Здравствуй, мир!</h1>;
+// "root" ссылается на идентификатор элемента.
+// Не переводите его!
+ReactDOM.render(element, document.getElementById('корень'));
+```
+
+❌ СОВСЕМ НЕЛЬЗЯ:
+
+```js
+// Пример
+const elemento = <h1>Здравствуй, мир!</h1>;
+ReactDOM.отрендери(elemento, documento.obtenerElementoPorId('корень'));
+```
+
+### Внешние ссылки
+
+Если внешняя ссылка ведёт к статье на [MDN] или [Wikipedia], и там существует статья на русском языке, исправьте ссылку, чтобы она указывала на русский вариант, даже если он неполный или требует улучшения.
+
+[MDN]: https://developer.mozilla.org/en-US/
+[Wikipedia]: https://en.wikipedia.org/wiki/Main_Page
+
+Пример:
+
+```md
+React elements are [immutable](https://en.wikipedia.org/wiki/Immutable_object).
+```
+
+✅ OK:
+
+```md
+Элементы React [иммутабельны](https://ru.wikipedia.org/wiki/%D0%9D%D0%B5%D0%B8%D0%B7%D0%BC%D0%B5%D0%BD%D1%8F%D0%B5%D0%BC%D1%8B%D0%B9_%D0%BE%D0%B1%D1%8A%D0%B5%D0%BA%D1%82).
+```
+
+Для ссылок, у которых нету языковых эквивалентов (Stack Overflow, видео на YouTube, и т. д.), просто оставьте оригинальный вариант как есть.
+
+## Соглашение по переводу (глоссарий)
+
+**Пожалуйста, поддерживайте глоссарий в алфавитном порядке.**
 
 | Оригинальный термин | Перевод |
 | ------------------ | ---------- |
@@ -116,18 +228,18 @@
 | props | пропсы *(мн. ч.)* |
 | production | продакшен |
 | production mode | продакшен-режим |
-| reducer | редюсер |
-| reuse | повторное использование, переиспользование |
 | React | React |
 | React element | React-элемент, элемент React |
 | reconciliation | согласование |
+| reducer | редюсер |
+| ref | реф *(ед. ч.)* |
+| refs | рефы *(мн. ч.)* |
 | render(ing) | рендер, рендерить, отрендерить |
 | renderer | рендерер (*напр., поверхностный рендерер*) |
 | re-render(ing) | (по контексту) рендер, повторный рендер, последующий рендер, отрендерить снова |
 | render prop | рендер-проп *(ед. ч.)* |
 | render props | рендер-пропсы *(мн. ч.)* |
-| ref | реф *(ед. ч.)* |
-| refs | рефы *(мн. ч.)* |
+| reuse | повторное использование, переиспользование |
 | (previous/next) section | (предыдущая/следующая) глава *(только в разделе Основные понятия)* |
 | shallow | поверхностное (сравнение, равенство), поверхностный (рендеринг) |
 | side effect | побочный эффект |