Skip to content

Latest commit

 

History

History
287 lines (224 loc) · 22.5 KB

CONTRIBUTING.md

File metadata and controls

287 lines (224 loc) · 22.5 KB
Raw

Участие в переводе

Оформление

  • Символ отступа — это пробел (табуляция в файлах .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, даже если придётся изменить форматирование примера оригинальной документации.

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

Оригинал англоязычной документации находится по адресу doc-en.

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

<?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 на один уровень с 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, а второй — хеш актуальной английской версии.

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

--- 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.

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

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

# Настройка
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» — лучше предпочесть последнее.

Параметры и аргументы

Параметр — член функции, который принадлежит функции, составляет сигнатуру функции или метода. Аргумент — значение, которое передают в функцию или метод «снаружи», чтобы определить значение параметра. Аргумент допускается передавать в функцию, передать в функцию параметр — нельзя, поскольку он уже находится «внутри» функции.

Участники перевода руководствуются этими разъяснениями, даже если в оригинальной документации «параметры» и «аргументы» употребили некорректно.

Скобки

Скобки затрудняют и замедляют чтение. Читатель «спотыкается» о скобки. Но без скобок нельзя обойтись. «В скобки заключают слова и предложения, вставляемые в предложение с целью пояснения или дополнения высказываемой мысли, а также для каких-либо добавочных замечаний» — гласят правила русского языка.

При переводе не нужно брать в скобки названия параметров.

Например:

Функция больше не поддерживает передачу разделителя <parameter>separator</parameter> после массива <parameter>array</parameter>.

В примере названия параметров — полноценные и равноправные члены предложения.

Названия типов нужно брать в скобки.

Например:

Функция возвращает строку (<type>string</type>).

В этом примере слово string (вместе с тегами) взяли в скобки, потому что слово поясняет, что «строка», кроме словарного значения, означает тип данных.

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

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