Skip to content

Commit 98fc8e9

Browse files
authored
Update CONTRIBUTING.md Исправил формулировки
1 parent 65ef687 commit 98fc8e9

1 file changed

Lines changed: 25 additions & 27 deletions

File tree

CONTRIBUTING.md

Lines changed: 25 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,15 @@
22

33
## Оформление
44

5-
- Символ отступа — это пробел (табуляция в файлах `.xml` запрещена)
6-
- В документации используется буква `Ё`. Обращайте на это, пожалуйста, внимание.
5+
- Символ отступа — пробел. Табуляция в файлах с расширением`.xml` спровоцирует ошибку.
6+
- В документации пишут букву `ё`, чтобы исключить риск двойного прочтения.
77

88
## Рекомендации по переводу
99

1010
Комментарии к коду требуется переводить;
11-
описание вывода, например, `echo "You reload page $num times";` — тоже требуется перевести.
11+
описание вывода наподобие `echo "You reload page $num times";` — тоже переводится.
1212

13-
Исключение из правила перевода английских слов в коде —
14-
функция будет по-разному обрабатывать английский и русский варианты, например,
13+
Исключение: английские слова в коде не переводятся, если перевод на русский язык изменит поведение функции, например,
1514
`strtolower("Alex") === "alex"`, но `strtolower("Алексей") !== "алексей"`.
1615

1716
Заголовок примера `<title><function>func_name</function> example</title>`
@@ -20,67 +19,66 @@
2019
только со словом «метод».
2120

2221
При оформлении кода примеров переводчик придерживается стиля кодирования,
23-
который описывает стандартная PHP-рекомендация [PSR-12](https://www.php-fig.org/psr/psr-12/),
24-
даже если придётся изменить форматирование примера оригинальной документации.
22+
который описывает рекомендация [PER](https://www.php-fig.org/per/coding-style/),
23+
даже если потребуется изменить форматирование примера оригинальной документации.
2524

26-
Переводить следует максимально близко к оригинальному тексту с отступлениями, если это оправдано.
27-
Если не устраивает формулировка, сначала следует обновить английскую версию, а затем перевод.
25+
Оригинальный текст переводят предельно точно, отступления допускаются только для сохранения семантики, если буквальный перевод исказит смысл.
26+
При неточных или ошибочных формулировках в исходной документации вначале через запрос на слияние исправляют английскую версию, а только потом обновляют русскую.
2827

2928
## Актуализация перевода
3029

31-
Оригинал англоязычной документации находится по адресу [doc-en](https://github.com/php/doc-en).
30+
Оригинал англоязычной документации доступен по адресу [doc-en](https://github.com/php/doc-en).
3231

33-
Файлы русскоязычной документации имеют определённый формат. В начале каждого файла должна быть конструкция следующего вида:
32+
Файлы русскоязычной документации включают обязательные комментарии после XML-декларации. В начале каждого файла после XML-объявления указывают два комментария:
3433

3534
```xml
3635
<?xml version="1.0" encoding="utf-8"?>
3736
<!-- EN-Revision: 0abaad099e3ec6064ed8cf31553dcd5e3e3fdfba Maintainer: sergey Status: ready -->
3837
<!-- Reviewed: no -->
3938
```
4039

41-
где `0abaad099e3ec6064ed8cf31553dcd5e3e3fdfba` — полный номер коммита в англоязычной документации, последнего актуального на момент редактирования для данного файла.
42-
Это нужно для того, чтобы понимать, что именно переведено, а что ещё нет.
40+
где `0abaad099e3ec6064ed8cf31553dcd5e3e3fdfba` — полный хеш коммита в англоязычной документации, последнего актуального на момент редактирования файла. По хешу коммита определяется актуальность русскоязычных переводов.
4341

4442
### Отслеживание изменений
4543

4644
#### На сайте doc.php.net
4745

48-
Выберите русский язык на правой боковой панели, а затем используйте инструмент Outdated files.
49-
В таблице будут перечислены файлы, для которых необходимо обновить перевод.
46+
Выберите русский язык на правой боковой панели, а затем откройте инструмент Outdated files.
47+
В таблице перечисляются файлы, для которых требуется обновить перевод.
5048

51-
В столбце `en` указан хеш актуальной английской версии, а в столбце `ru` — хеш перевода.
49+
В столбце `en` указывается хеш актуальной английской версии, а в столбце `ru` — хеш перевода.
5250

5351
#### В командной строке
5452

5553
Клонируйте репозиторий [doc-base](https://github.com/php/doc-base) на один уровень с
56-
[doc-en](https://github.com/php/doc-en) и `doc-ru`, чтобы структура папок была следующей:
54+
[doc-en](https://github.com/php/doc-en) и `doc-ru`, чтобы получить следующую структуру папок:
5755

5856
```
5957
├── doc-base/
6058
├── en/
6159
└── ru/
6260
```
6361

64-
Обратите внимание, что языковые папки должны быть без префикса `doc-`.
62+
Обратите внимание: языковые папки не содержат префикса `doc-`.
6563

66-
Для клонирования можно воспользоваться командой `git clone https://github.com/php/doc-ru.git ru`.
64+
Русскоязычный репозиторий клонируют командой: `git clone https://github.com/php/doc-ru.git ru`.
6765

68-
Выполните следующую команду в терминале и откройте получившийся `revcheck.html` в браузере:
66+
Выполните следующую команду в терминале и откройте файл `revcheck.html` в браузере:
6967

7068
```
7169
php doc-base/scripts/revcheck.php ru > revcheck.html
7270
```
73-
В разделе Outdated Files можно посмотреть актуальную английскую версию и текущую.
71+
В разделе Outdated Files доступен просмотр актуальной английской версии и текущей.
7472

7573
### Просмотр изменений
7674

77-
Чтобы посмотреть, какие изменения были произведены, выполните следующую команду:
75+
Для просмотра изменений выполняют следующую команду:
7876

7977
```
8078
git --no-pager diff 8b5940cadeb4f1c8492f4a7f70743a2be807cf39 68a9c82e06906a5c00e0199307d87dd3739f719b reference/array/functions/in-array.xml
8179
```
8280

83-
где первый хеш — это текущая версия из `EN-Revision`, а второй — хеш актуальной английской версии.
81+
где первый хеш — текущая версия из `EN-Revision`, а второй — хеш актуальной английской версии.
8482

8583
Пример вывода:
8684

@@ -97,10 +95,10 @@ git --no-pager diff 8b5940cadeb4f1c8492f4a7f70743a2be807cf39 68a9c82e06906a5c00e
9795
</refsect1>
9896
```
9997

100-
Как видите, изменилось описание функции.
98+
Вывод показывает, что изменилось описание функции.
10199

102-
Строка `Searches <parameter>haystack</parameter> for <parameter>needle</parameter> using loose comparison`
103-
заменена на `Searches for <parameter>needle</parameter> in <parameter>haystack</parameter> using loose comparison`.
100+
Строку `Searches <parameter>haystack</parameter> for <parameter>needle</parameter> using loose comparison`
101+
заменили на `Searches for <parameter>needle</parameter> in <parameter>haystack</parameter> using loose comparison`.
104102

105103
Откройте файл `reference/array/functions/in-array.xml` в репозитории `doc-ru`
106104
и измените строку в соответствии с английской версией.
@@ -109,7 +107,7 @@ git --no-pager diff 8b5940cadeb4f1c8492f4a7f70743a2be807cf39 68a9c82e06906a5c00e
109107

110108
## Проверка отображения перевода
111109

112-
Для локального просмотра документации, выполните следующие команды в терминале:
110+
Для локального просмотра документации выполните в терминале следующие команды:
113111

114112
````bash
115113
# Настройка

0 commit comments

Comments
 (0)