# Участие в переводе
## Оформление
- Символ отступа — это пробел (табуляция в файлах `.xml` запрещена)
- В документации используется буква `Ё`. Обращайте на это, пожалуйста, внимание.
## Рекомендации по переводу
Комментарии к коду требуется переводить;
описание вывода, например, `echo "You reload page $num times";` — тоже требуется перевести.
Исключение из правила перевода английских слов в коде —
функция будет по-разному обрабатывать английский и русский варианты, например,
`strtolower("Alex") === "alex"`, но `strtolower("Алексей") !== "алексей"`.
Заголовок примера `<function>func_name</function> example`
переводится как `Пример [что делает функция, в родительном падеже] функцией <function>func_name</function>`:
`Пример слияния массивов функцией <function>function_name</function>`. То же правило справедливо для методов,
только со словом «метод».
При оформлении кода примеров переводчик придерживается стиля кодирования,
который описывает стандартная PHP-рекомендация [PSR-12](https://www.php-fig.org/psr/psr-12/),
даже если придётся изменить форматирование примера оригинальной документации.
Переводить следует максимально близко к оригинальному тексту с отступлениями, если это оправдано.
Если не устраивает формулировка, сначала следует обновить английскую версию, а затем перевод.
## Актуализация перевода
Оригинал англоязычной документации находится по адресу [doc-en](https://github.com/php/doc-en).
Файлы русскоязычной документации имеют определённый формат. В начале каждого файла должна быть конструкция следующего вида:
```xml
```
где `0abaad099e3ec6064ed8cf31553dcd5e3e3fdfba` — полный номер коммита в англоязычной документации, последнего актуального на момент редактирования для данного файла.
Это нужно для того, чтобы понимать, что именно переведено, а что ещё нет.
### Отслеживание изменений
#### На сайте doc.php.net
Выберите русский язык на правой боковой панели, а затем используйте инструмент Outdated files.
В таблице будут перечислены файлы, для которых необходимо обновить перевод.
В столбце `en` указан хеш актуальной английской версии, а в столбце `ru` — хеш перевода.
#### В командной строке
Клонируйте репозиторий [doc-base](https://github.com/php/doc-base) на один уровень с
[doc-en](https://github.com/php/doc-en) и `doc-ru`, чтобы структура папок была следующей:
```
├── doc-base/
├── en/
└── ru/
```
Обратите внимание, что языковые папки должны быть без префикса `doc-`.
Для клонирования можно воспользоваться командой `git clone https://github.com/php/doc-ru.git ru`.
Выполните следующую команду в терминале и откройте получившийся `revcheck.html` в браузере:
```
php doc-base/scripts/revcheck.php ru > revcheck.html
```
В разделе Outdated Files можно посмотреть актуальную английскую версию и текущую.
### Просмотр изменений
Чтобы посмотреть, какие изменения были произведены, выполните следующую команду:
```
git --no-pager diff 8b5940cadeb4f1c8492f4a7f70743a2be807cf39 68a9c82e06906a5c00e0199307d87dd3739f719b reference/array/functions/in-array.xml
```
где первый хеш — это текущая версия из `EN-Revision`, а второй — хеш актуальной английской версии.
Пример вывода:
```diff
--- a/reference/array/functions/in-array.xml
+++ b/reference/array/functions/in-array.xml
@@ -14,7 +14,7 @@
boolstrict&false;
- Searches haystack for needle using loose comparison
+ Searches for needle in haystack using loose comparison unless strict is set.
```
Как видите, изменилось описание функции.
Строка `Searches haystack for needle using loose comparison`
заменена на `Searches for needle in haystack using loose comparison`.
Откройте файл `reference/array/functions/in-array.xml` в репозитории `doc-ru`
и измените строку в соответствии с английской версией.
Затем обновите комментарий `EN-Revision`.
## Проверка отображения перевода
Для локального просмотра документации, выполните следующие команды в терминале:
````bash
# Настройка
git clone https://github.com/php/phd.git
git clone https://github.com/php/doc-base.git
git clone https://github.com/php/doc-ru.git ru
# Проверка изменений
php doc-base/configure.php --with-lang=ru
php phd/render.php --docbook doc-base/.manual.xml --package PHP --format xhtml
# Откройте output/php-chunked-xhtml/ в браузере.
````
## Соглашение по переводу
| Оригинал | Перевод |
|---------------------------------|-----------------------------------------------------------------------|
| Application | Приложение |
| Cache | Кеш |
| Callback function | Callback-функция |
| Child | Потомок, дочерний элемент (узел) |
| CLI | Интерфейс командной строки |
| Code (php-code) | Код, PHP-код |
| Coding standards | Стандарты кодирования |
| Commandline program | Консольная программа |
| Commit | Фиксация (например, транзакции) |
| Default, by default | По умолчанию (пишется без дефиса) |
| Directory | Директория |
| Download | Скачать (не то же, что «загрузить», см. Load) |
| Entry | Элемент (существительное, для массивов, списков и прочих структур) |
| Expression | Выражение |
| Extension | Модуль |
| Features/functionality | Возможности, функциональность |
| Fiber | Файбер |
| Float (floating point) | Число с плавающей точкой (плавающая точка) |
| Fully Qualified name | Абсолютное имя |
| Getter | Метод чтения |
| Global scope | Глобальное пространство |
| Hash | Хеш |
| HTML entity | HTML-сущность |
| HTTP-Authentication | HTTP-аутентификация |
| Hypertext preprocessor | Препроцессор гипертекста |
| Handle | Дескриптор (например, cURL) или обработчик (кроме cURL) |
| ID (БД) | ID |
| ID (в тексте) | Идентификатор |
| Legacy (system, server) | Устаревшая система, сервер, протокол |
| Legacy support | Поддержка старых версий |
| Load | Загрузить (не то же, что «скачать», см. Download) |
| Locale | Региональные настройки или параметры; локаль |
| Magic quotes | «Магические» кавычки |
| Magic constants/methods/numbers | «Магические» константы/методы/числа |
| Multibyte string | Многобайтовая строка |
| Namespace | Пространство имён |
| Node | Узел |
| Optional | Необязательный |
| Override | Переопределять |
| Otherwise | В противном случае (только в начале предложения! — прим.), иначе |
| On success | В случае успешного выполнения |
| On fail/failure | Если возникла ошибка |
| Parameter(s) | Параметр(ы), аргумент(ы) |
| Parser | Парсер |
| Parsing | Разбор (например, разбор строки) |
| Prefetch | Предварительная выборка |
| PCRE | Perl-совместимые регулярные выражения |
| PHP value | PHP-значение |
| Private | Закрытый |
| Protected | Защищённый |
| Public | Общедоступный или открытый |
| Qualified name | Полное имя |
| Read-only | Доступен только для чтения |
| Result set | Результирующий набор |
| Returns | Возвращает |
| SAPI | Интерфейс разработки серверных приложений |
| Script | Скрипт |
| Setter | Устанавливающий метод |
| Single quotes | Одинарные кавычки |
| Stream | Поток |
| Shared block | Общая блокировка |
| Shared memory | Разделяемая память |
| SQL query | Запрос SQL, SQL-запрос |
| SQL | Структурированный язык запросов |
| Statement | Инструкция |
| Throw exception | Выбросить исключение |
| Timeout | Время ожидания |
| Timezone, time zone | Часовой пояс |
| Token | Лексема |
| Tokenizer | Лексер |
| To throw a warning/error | Вызвать предупреждение или ошибку |
| Trait | Трейт |
| Writable | Доступен для записи |
| Wrapper | Обёртка |
| Unqualified name | Неполное имя |
| Upload | Выгрузить или переданные, или отправленные, данные; но не «загрузка») |
| URL wrapper | Обёртка URL |
## Не переводятся
- Apache
- Cookie
- Linux
- PEAR
- PECL
- PHP Group
- PHP
- Referer
- Windows
- Имена переменных
- Типы переменных (integer, string, bool, resource)
И другие аббревиатуры или имена собственные.
## Сопроводительные, или уточняющие, слова
Когда в английской документации встречаются термины —
аббревиатуры, названия параметров, функций или методов, имена констант, операционных систем и т. д. —
без сопровождающих слов, которые указывают, к какому предмету относится термин,
необходимо добавить уточняющее слово.
Например:
| Оригинал | Перевод |
|---------------------------------|-----------------------------------------------------------------------|
| `$foo` | Переменная `$foo` |
| `$_SERVER` | Суперглобальная переменная `$_SERVER` |
| `__METHOD__` | Магическая константа `__METHOD__` |
| `foo` | Параметр `foo` |
| `echo` | Языковая конструкция `echo` |
| Apache | Веб-сервер Apache, или Модуль Apache |
| Content-Length | Заголовок Content-Length |
| CURLOPT_HEADER | Параметр CURLOPT_HEADER |
| CURLINFO_HTTP_CODE | Опция CURLINFO_HTTP_CODE |
| SAPI | Интерфейс SAPI |
| Linux | Семейство операционных систем Linux или Linux-системы |
| PHP_VERSION | Константа PHP_VERSION |
| `var_dump()` | Функция `var_dump()` |
Одного уточнения хватит, если в предложении или коротком абзаце термин встречается больше одного раза, по смыслу.
При добавлении уточняющего слова дайте точное определение. Для термина `$_SERVER` доступны
уточнения: «Переменная $_SERVER», «Глобальная переменная $_SERVER» или «Суперглобальная переменная $_SERVER» — лучше предпочесть последнее.
## Параметры и аргументы
Параметр — член функции, который принадлежит функции, составляет сигнатуру функции или метода.
Аргумент — значение, которое передают в функцию или метод «снаружи», чтобы определить значение параметра.
Аргумент допускается передавать в функцию, передать в функцию параметр — нельзя, поскольку он уже находится «внутри» функции.
Участники перевода руководствуются этими разъяснениями, даже если в оригинальной документации «параметры»
и «аргументы» употребили некорректно.
## Скобки
Скобки затрудняют и замедляют чтение. Читатель «спотыкается» о скобки. Но без скобок нельзя обойтись. «В скобки заключают
слова и предложения, вставляемые в предложение с целью пояснения или дополнения высказываемой мысли, а также
для каких-либо добавочных замечаний» — гласят правила русского языка.
При переводе не нужно брать в скобки названия параметров.
Например:
> Функция больше не поддерживает передачу разделителя `separator` после массива `array`.
В примере названия параметров — полноценные и равноправные члены предложения.
Названия типов нужно брать в скобки.
Например:
> Функция возвращает строку (`string`).
В этом примере слово string (вместе с тегами) взяли в скобки, потому что слово поясняет,
что «строка», кроме словарного значения, означает тип данных.
Старайтесь избавиться от скобок, если уместно (если это не часть примера или выражения и т. д.),
даже если в исходной документации слова или предложения указали в скобках.
Точку ставят после закрывающей скобки, если слова в скобках — часть предложения (как в этом примере).
(Точку ставят перед закрывающей скобкой, если в скобках написано отдельное предложение — как здесь.)