Документація Laravel тепер доступна українською - усі 103 сторінки версії 13.x, від маршрутизації та Eloquent до Passport і Horizon. Читати можна просто на сайті, з пошуком по 4295 секціях і звичною бічною панеллю з 11 розділів.
Перекласти документацію - половина справи. Друга половина починається наступного дня, коли апстрім вносить чергову правку, і переклад тихо застаріває. Саме на цьому зазвичай і закінчуються спроби локалізації: перший захід робиться на ентузіазмі, а на другий рік хтось відкриває сторінку про черги й бачить API, якого вже два релізи як немає.
Тому синхронізація тут автоматична, і влаштована так, щоб щодня наздоганяти правку в кілька рядків, а не перекладати сторінку заново.
Кожна сторінка пам'ятає свій коміт
Перший рядок кожного перекладеного файлу - хеш коміту laravel/docs, з якого його перекладено:
---
git: 8042e4ce5c44b0ad51476cb1fb915af086047edb
---
Це і є джерело правди про відставання. Немає окремої бази, яку треба тримати в актуальному стані, немає таблиці відповідностей, яку легко забути оновити: стан перекладу виводиться з самих файлів. Якщо хтось перекладе сторінку вручну й забуде оновити хеш - наступний прогін просто перекладе ті самі зміни ще раз, і це найгірше, що станеться.
Перекладаються тільки змінені секції
Сторінки документації сягають чотирьох тисяч рядків, а типовий коміт апстріму змінює двадцять. Віддавати strings.md цілком, щоб перейменувати один метод, - це переписати заново весь файл заради двох рядків правки, а разом із ним і всі шанси десь дорогою щось зіпсувати.
Тому файл ріжеться на секції за якорями <a name="..."></a>, і в модель іде лише та секція, якої торкнувся diff, разом із самим diff. Решта копіюється байт у байт - модель їх навіть не бачить, а отже не може зіпсувати.
Структуру перевіряє валідатор, а не людина
Переклад документації має збігатися з оригіналом структурно: сайт рендерить обидва з того самого Markdown, бічна панель будується з якорів, а глибокі посилання ведуть саме на них. Модель, яка загубила якір або злила два блоки коду, дає сторінку, яка в diff виглядає нормально, а на сайті зламана.
Тому перед записом кожна сторінка звіряється з англійським оригіналом:
- кількість рядків - рівно стільки ж плюс три рядки заголовка;
- якорі - той самий набір у тому самому порядку;
- блоки коду - та сама кількість огорож;
- внутрішні посилання - жодного, що вказує на неіснуючий якір.
Сторінка, яка не пройшла перевірку, не потрапляє в pull request. Нещодавно це спрацювало на installation.md: модель повернула секцію на два рядки коротшою, з'ївши порожній рядок біля блоку коду, - і сторінку було відхилено автоматично, без участі людини.
Що робить автоматика, а що лишає людям
Свідомо не автоматизовано дві речі.
Нові сторінки. Увесь механізм побудований на diff між двома комітами: беремо те, що змінилося від часу нашого перекладу. Для сторінки, якої в перекладі ще немає, порівнювати немає з чим - її треба перекладати цілком. Це вже не двадцять рядків правки, а сотні: сторінка про Laravel Head, приміром, має 762 рядки. Тому замість тихого нічного прогону заводиться issue. Саме так цього тижня з'явилася сторінка про Laravel Head: текст так само переклала модель, але окремим заходом і під наглядом людини.
Великі зміни. Якщо апстрім переписав розділ цілком, прогін не береться за нього, а звітує - переписаний з нуля розділ вартий уваги людини.
Переклад машинний, і ми цього не приховуємо
Головне, що варто сказати прямо: весь текст переклала модель. Базовий переклад усіх 103 сторінок робив Opus - найсильніша модель Anthropic, і саме тому текст вийшов пристойним. Щоденні зміни за diff наздоганяє Sonnet: там ідеться про десятки рядків, вписаних у вже готовий переклад із заданою термінологією і стилем. З цим він справляється впевнено.
Далі текст читають люди. Кожен прогін приходить окремим pull request, і зміни переглядають перед злиттям - саме тому в описі кожного PR стоїть нагадування, що структуру перевірено автоматично, а текст потребує вичитки.
Автоматика бере на себе рівно те, що можна перевірити машинно. Валідатор ловить структурні поломки - загублений якір, зниклий блок коду, роз'їхану кількість рядків. Кострубату фразу, невдалий термін чи зміщений акцент він не ловить: це лишається людині.
Вичитка триває, і це робота надовго. Тому якщо ви відкрили сторінку й перечепилися за формулювання - не проходьте повз:
- репозиторій перекладу відкритий, PR вітаються;
- у ньому є глосарій з усталеною термінологією - єдиний словник важливіший за красу окремої фрази;
- правити варто український файл, а не англійський оригінал: апстрім підтягується автоматично.
Найкорисніші правки - не орфографічні, а термінологічні: якщо у вас є аргумент, чому middleware в конкретному контексті слід перекладати інакше, ніж каже глосарій, це рядок у словнику, а не лише в одному файлі.
З чого почати
Якщо ви тільки заходите в Laravel - встановлення і структура каталогів. Якщо вже пишете - найкорисніші українською зазвичай ті розділи, які читають найуважніше: Eloquent, черги і валідація.
Пошук працює по секціях, а не по сторінках, тож whereHas чи retryUntil приведуть одразу до потрібного абзацу, а не до чотиритисячного файлу, у якому це слово десь є.
Ми не вважаємо, що український переклад має замінити англійський оригінал. Хто вільно читає англійською, той і далі читатиме laravel.com/docs - і правильно робитиме. Але між «прочитати розділ рідною за десять хвилин» і «продиратися через нього годину зі словником» різниця не в зручності, а в тому, чи дочитає людина взагалі.
Саме заради цього все й затівалося. Документація жива, поки за нею встигають: тепер вона встигає сама, щодня, без чийогось вечора, витраченого на звірку з апстрімом. Лишається те, що під силу тільки людині, - зробити так, щоб цей текст читався українською, а не перекладеною англійською. Тут ми розраховуємо на вас.
