Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
287 lines (223 loc) · 23.5 KB

CONTRIBUTING.md

File metadata and controls

287 lines (223 loc) · 23.5 KB
Raw

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

Оформление

  • Символ отступа — пробел; табуляция в файлах с расширением.xml спровоцирует ошибку. В 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>. То же правило справедливо для методов, только со словом «метод».

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

Оригинальный текст переводят предельно точно, отступления допускаются только для сохранения семантики, если буквальный перевод исказит смысл. При неточных или ошибочных формулировках в исходной документации вначале исправляют английскую версию путём отправки запроса на слияние, а только потом обновляют русскую.

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

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

Файлы русскоязычной документации включают обязательные комментарии после XML-декларации. В начале каждого файла после 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 на один уровень с 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 вместе с тегами взяли в скобки, потому что слово поясняет, что «строка», кроме словарного значения, означает тип данных.

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

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