php
Улучшение документации
Предлагаю после завершения перевода (#113) заняться улучшением документации.
У файлов есть тег Reviewed, хотя есть вопросы к его актуальности (у части файлов он помечен yes, но без указания проверяющего — такие предлагаю перевести в статус no).
Необходимо проверить все файлы с Reviewed: no, а в идеале, ещё и с Reviewed: yes перепроверить.
Чек лист
Соответствие тегов и их значений
Количество тегов (<literal>, <varname>, ∫, <type>string</type> и т.д.) должно соответствовать английской версии.
Заголовки функций
Заголовок функции refpurpose должен быть в 3 лице, единственном числе и отвечать на вопрос "Что функция делает?", если это допустимо.
Пример — "Пропорционально изменяет размер изображения".
Точка в заголовке не ставится.
Комментарии в коде
Комментарии в коде должны быть переведены. Комментарии в коде, объясняющие действие, должны быть написаны в форме глагольного существительного, где это уместно. Пример — "выполнение запроса" (а не "выполнить запрос", "выполняем запрос" и т.д.)
Заголовки примеров
Если в английской версии заголовок примера вместо function() example, например, просто function() ,
в русской версии заголовок должен всё равно быть Пример использования function().
Правильное написание терминов и слов
Если в английской версии используется mysql или blob, в русской версии всё равно используем MySQL и BLOB, соответственно.
Лишние пустые строки и отступы
Лишние пустые строки и отступы удаляются, refsect-блоки разделяются 1 пустой строкой (если отступа нет, наоборот его необходимо добавить)
Комментарии в тексте
Комментарии, не относящиеся к переводу документации необходимо удалить. Например,
<!-- TODO: we don't need further details here, but this still has to be
added to the operator precedence table -->
<!-- TODO Drop mention of crypt? -->
Единообразность терминов
Иногда термины переводятся по-разному, пока не приходит в голову простое решение, как во всей документации поддерживать однообразность, кроме как создания большой вики, но это кажется лишним 😞
Сокращение англицизмов
По возможности, сокращать перевод "this". Например, "this function crops the image", можно перевести, как "функция обрезает изображение", уточнение "эта" будет лишним. В то же время, там где это местно, можно смело оставлять.
Мелочи
Если в английской версии предложение начинается с маленькой буквы, в русской версии делаем нормально :) Точки в конце предложения тоже ставим, если они отсутствуют в оригинале. Используем кавычки-ёлочки, где это уместно.
Персонализация
Не рекомендуется использовать "вы", "мы" и другие местоимения для персонализации, даже если в английской версии персонализированная фраза.
Пример: НЕПРАВИЛЬНО: "Вы можете использовать второй параметр для ..." ПРАВИЛЬНО: "Второй параметр используется для..."
Параметры, константы и т.д.
Если в английской версии отсутствует указатель на тип сущности, например,
If <parameter>key</parameter> exists, предпочтительнее перевести как:
Если параметр <parameter>key</parameter> существует,
добавив предполагаемый "параметр".
Блок Return Values
Всегда начинается с "Функция/метод возвращает..."
Чек лист на финальную версию не претендует, все пункты обсждаются =)
Спрошу здесь, возможно, это начнёт обсуждение.
В глоссарии соответствий time zone предлагается переводить как «временная зона», в то время как общепринятый перевод — «часовой пояс». Есть какие-то причины этого выбора? Спрашиваю, поскольку, во-первых, много лет проработал в локализации :), а во-вторых, человек или люди, которые составляли этот глоссарий, кажутся мне опытными профессионалами, ибо больше вопросов у меня (обычно страшно привередливого и, чего греха таить, любящего отстаивать свою точку зрения) вообще не возникло.
Спасибо!
@Menelion, спасибо!
Часть соглашения была написана, когда уже большой объем текста был переведён, думаю, просто взяли вариант, который чаще встречается 🤔
Если есть более удачный вариант перевода, можно внести изменение в соглашение =)
Мне тоже кажется, что лучше использовать "часовой пояс", "временная зона" звучит как калька.
Согласен, давайте тогда заменим :)
Предлагаю тогда в новых переводах сразу использовать "часовой пояс", если встретится. А в существующих переводах заменим на этапе вычитки.
Upd: Заодно, может, ещё какие-то варианты улучшим/добавим.
Обсуждение
Для подобных исправлений (а также опечаток в оригинале) предложили добавить тег [skip-revcheck] в теле коммита.
То есть, скорее всего, через какое-то время мы получим рассинхнон в тегах (&return.falseforfailure;, &null; и т.д.)
за совпадением которых мы сейчас следим.
Пока добиваем переводы, понаблюдаем за ситуацией, но если рассинхрон появится, думаю, можно будет тогда отступать от оригинала и какие-то вещи улучшать (например, фразы заменять сниппетами &return.*) 🤔
Количество тегов (
<literal>,<varname>,∫,<type>string</type>и т.д.) должно соответствовать английской версии.
Если что, у меня где-то валяется php скрипт для поиска устаревшей документации: он рекурсивно обходит все элементы исходного документа(DOMElement::$childNodes) и сравнивает с переводом по имени(DOMElement::$tagName), добавляя отсутствующие элементы.
Если что пишите, попробую найти и скинуть.
Хотя логичнее было бы добавить действие/задачу в workflow php/doc-en которая бы срабатывала при изменении репозитория и обновляла сразу все переводы. Список измененных файлов можно взять из последнего влитого PR т.ч. не придется сравнивать все файлы.
