mirror of
https://github.com/php/doc-ru.git
synced 2026-03-23 23:32:16 +01:00
291 lines
23 KiB
Markdown
291 lines
23 KiB
Markdown
# Участие в переводе
|
||
|
||
## Оформление
|
||
|
||
- Символ отступа — это пробел (табуляция в файлах `.xml` запрещена)
|
||
- В документации используется буква `Ё`. Обращайте на это, пожалуйста, внимание.
|
||
|
||
## Рекомендации по переводу
|
||
|
||
Комментарии к коду требуется переводить;
|
||
описание вывода, например, `echo "You reload page $num times";` — тоже требуется перевести.
|
||
|
||
Исключение из правила перевода английских слов в коде —
|
||
функция будет по-разному обрабатывать английский и русский варианты, например,
|
||
`strtolower("Alex") === "alex"`, но `strtolower("Алексей") !== "алексей"`.
|
||
|
||
Заголовок примера `<title><function>func_name</function> example</title>`
|
||
переводится как `<title>Пример [что делает функция, в родительном падеже] функцией <function>func_name</function></title>`:
|
||
`<title>Пример слияния массивов функцией <function>function_name</function></title>`. То же правило справедливо для методов,
|
||
только со словом «метод».
|
||
|
||
При оформлении кода примеров переводчик придерживается стиля кодирования,
|
||
который описывает стандартная PHP-рекомендация [PSR-12](https://www.php-fig.org/psr/psr-12/),
|
||
даже если придётся изменить форматирование примера оригинальной документации.
|
||
|
||
Переводить следует максимально близко к оригинальному тексту с отступлениями, если это оправдано.
|
||
Если не устраивает формулировка, сначала следует обновить английскую версию, а затем перевод.
|
||
|
||
## Актуализация перевода
|
||
|
||
Оригинал англоязычной документации находится по адресу [doc-en](https://github.com/php/doc-en).
|
||
|
||
Файлы русскоязычной документации имеют определённый формат. В начале каждого файла должна быть конструкция следующего вида:
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="utf-8"?>
|
||
<!-- EN-Revision: 0abaad099e3ec6064ed8cf31553dcd5e3e3fdfba Maintainer: sergey Status: ready -->
|
||
<!-- Reviewed: no -->
|
||
```
|
||
|
||
где `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 @@
|
||
<methodparam choice="opt"><type>bool</type><parameter>strict</parameter><initializer>&false;</initializer></methodparam>
|
||
</methodsynopsis>
|
||
<para>
|
||
- Searches <parameter>haystack</parameter> for <parameter>needle</parameter> using loose comparison
|
||
+ Searches for <parameter>needle</parameter> in <parameter>haystack</parameter> using loose comparison unless <parameter>strict</parameter> is set.
|
||
</para>
|
||
</refsect1>
|
||
```
|
||
|
||
Как видите, изменилось описание функции.
|
||
|
||
Строка `Searches <parameter>haystack</parameter> for <parameter>needle</parameter> using loose comparison`
|
||
заменена на `Searches for <parameter>needle</parameter> in <parameter>haystack</parameter> 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__` |
|
||
| `<parameter>foo</parameter>` | Параметр `<parameter>foo</parameter>` |
|
||
| `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» — лучше предпочесть последнее.
|
||
|
||
## Параметры и аргументы
|
||
|
||
Параметр — член функции, который принадлежит функции, составляет сигнатуру функции или метода.
|
||
Аргумент — значение, которое передают в функцию или метод «снаружи», чтобы определить значение параметра.
|
||
Аргумент допускается передавать в функцию, передать в функцию параметр — нельзя, поскольку он уже находится «внутри» функции.
|
||
|
||
Участники перевода руководствуются этими разъяснениями, даже если в оригинальной документации «параметры»
|
||
и «аргументы» употребили некорректно.
|
||
|
||
## Скобки
|
||
|
||
Скобки затрудняют и замедляют чтение. Читатель «спотыкается» о скобки. Но без скобок нельзя обойтись. «В скобки заключают
|
||
слова и предложения, вставляемые в предложение с целью пояснения или дополнения высказываемой мысли, а также
|
||
для каких-либо добавочных замечаний» — гласят правила русского языка.
|
||
|
||
При переводе <em>не нужно</em> брать в скобки названия параметров.
|
||
|
||
Например:
|
||
|
||
> Функция больше не поддерживает передачу разделителя `<parameter>separator</parameter>` после массива `<parameter>array</parameter>`.
|
||
|
||
В примере названия параметров — полноценные и равноправные члены предложения.
|
||
|
||
Названия типов <em>нужно</em> брать в скобки.
|
||
|
||
Например:
|
||
|
||
> Функция возвращает строку (`<type>string</type>`).
|
||
|
||
В этом примере слово string (вместе с тегами) взяли в скобки, потому что слово поясняет,
|
||
что «строка», кроме словарного значения, означает тип данных.
|
||
|
||
Старайтесь избавиться от скобок, если уместно (если это не часть примера или выражения и т. д.),
|
||
даже если в исходной документации слова или предложения указали в скобках.
|
||
|
||
Точку ставят после закрывающей скобки, если слова в скобках — часть предложения (как в этом примере).
|
||
(Точку ставят перед закрывающей скобкой, если в скобках написано отдельное предложение — как здесь.)
|