--- title: "Документація Laravel українською: 103 сторінки і щоденна синхронізація" url: https://laravelukraine.com/blog/dokumentaciia-laravel-ukrayinskoiu-103-storinki-i-shhodenna-sinxronizaciia date: 2026-08-07 --- # Документація Laravel українською: 103 сторінки і щоденна синхронізація [Документація Laravel](https://laravelukraine.com/docs) тепер доступна українською - усі 103 сторінки версії 13.x, від маршрутизації та Eloquent до Passport і Horizon. Читати можна просто на сайті, з пошуком по 4295 секціях і звичною бічною панеллю з 11 розділів. Перекласти документацію - половина справи. Друга половина починається наступного дня, коли апстрім вносить чергову правку, і переклад тихо застаріває. Саме на цьому зазвичай і закінчуються спроби локалізації: перший захід робиться на ентузіазмі, а на другий рік хтось відкриває сторінку про черги й бачить API, якого вже два релізи як немає. Тому синхронізація тут автоматична, і влаштована так, щоб щодня наздоганяти правку в кілька рядків, а не перекладати сторінку заново. ### Кожна сторінка пам'ятає свій коміт Перший рядок кожного перекладеного файлу - хеш коміту `laravel/docs`, з якого його перекладено: ```markdown --- git: 8042e4ce5c44b0ad51476cb1fb915af086047edb --- ``` Це і є джерело правди про відставання. Немає окремої бази, яку треба тримати в актуальному стані, немає таблиці відповідностей, яку легко забути оновити: стан перекладу виводиться з самих файлів. Якщо хтось перекладе сторінку вручну й забуде оновити хеш - наступний прогін просто перекладе ті самі зміни ще раз, і це найгірше, що станеться. ### Перекладаються тільки змінені секції Сторінки документації сягають чотирьох тисяч рядків, а типовий коміт апстріму змінює двадцять. Віддавати `strings.md` цілком, щоб перейменувати один метод, - це переписати заново весь файл заради двох рядків правки, а разом із ним і всі шанси десь дорогою щось зіпсувати. Тому файл ріжеться на секції за якорями ``, і в модель іде лише та секція, якої торкнувся diff, разом із самим diff. Решта копіюється байт у байт - модель їх навіть не бачить, а отже не може зіпсувати. ### Структуру перевіряє валідатор, а не людина Переклад документації має збігатися з оригіналом структурно: сайт рендерить обидва з того самого Markdown, бічна панель будується з якорів, а глибокі посилання ведуть саме на них. Модель, яка загубила якір або злила два блоки коду, дає сторінку, яка в diff виглядає нормально, а на сайті зламана. Тому перед записом кожна сторінка звіряється з англійським оригіналом: - кількість рядків - рівно стільки ж плюс три рядки заголовка; - якорі - той самий набір у тому самому порядку; - блоки коду - та сама кількість огорож; - внутрішні посилання - жодного, що вказує на неіснуючий якір. Сторінка, яка не пройшла перевірку, не потрапляє в pull request. Нещодавно це спрацювало на `installation.md`: модель повернула секцію на два рядки коротшою, з'ївши порожній рядок біля блоку коду, - і сторінку було відхилено автоматично, без участі людини. ### Що робить автоматика, а що лишає людям Свідомо не автоматизовано дві речі. **Нові сторінки.** Увесь механізм побудований на diff між двома комітами: беремо те, що змінилося від часу нашого перекладу. Для сторінки, якої в перекладі ще немає, порівнювати немає з чим - її треба перекладати цілком. Це вже не двадцять рядків правки, а сотні: сторінка про Laravel Head, приміром, має 762 рядки. Тому замість тихого нічного прогону заводиться issue. Саме так цього тижня з'явилася сторінка про [Laravel Head](https://laravelukraine.com/docs/13.x/head): текст так само переклала модель, але окремим заходом і під наглядом людини. **Великі зміни.** Якщо апстрім переписав розділ цілком, прогін не береться за нього, а звітує - переписаний з нуля розділ вартий уваги людини. ### Переклад машинний, і ми цього не приховуємо Головне, що варто сказати прямо: весь текст переклала модель. Базовий переклад усіх 103 сторінок робив Opus - найсильніша модель Anthropic, і саме тому текст вийшов пристойним. Щоденні зміни за diff наздоганяє Sonnet: там ідеться про десятки рядків, вписаних у вже готовий переклад із заданою термінологією і стилем. З цим він справляється впевнено. Далі текст читають люди. Кожен прогін приходить окремим pull request, і зміни переглядають перед злиттям - саме тому в описі кожного PR стоїть нагадування, що структуру перевірено автоматично, а текст потребує вичитки. Автоматика бере на себе рівно те, що можна перевірити машинно. Валідатор ловить структурні поломки - загублений якір, зниклий блок коду, роз'їхану кількість рядків. Кострубату фразу, невдалий термін чи зміщений акцент він не ловить: це лишається людині. Вичитка триває, і це робота надовго. Тому якщо ви відкрили сторінку й перечепилися за формулювання - не проходьте повз: - [репозиторій перекладу](https://github.com/laravelukraine/docs) відкритий, PR вітаються; - у ньому є [глосарій](https://github.com/laravelukraine/docs/blob/13.x/GLOSSARY.md) з усталеною термінологією - єдиний словник важливіший за красу окремої фрази; - правити варто український файл, а не англійський оригінал: апстрім підтягується автоматично. Найкорисніші правки - не орфографічні, а термінологічні: якщо у вас є аргумент, чому `middleware` в конкретному контексті слід перекладати інакше, ніж каже глосарій, це рядок у словнику, а не лише в одному файлі. ### З чого почати Якщо ви тільки заходите в Laravel - [встановлення](https://laravelukraine.com/docs/13.x/installation) і [структура каталогів](https://laravelukraine.com/docs/13.x/structure). Якщо вже пишете - найкорисніші українською зазвичай ті розділи, які читають найуважніше: [Eloquent](https://laravelukraine.com/docs/13.x/eloquent), [черги](https://laravelukraine.com/docs/13.x/queues) і [валідація](https://laravelukraine.com/docs/13.x/validation). Пошук працює по секціях, а не по сторінках, тож `whereHas` чи `retryUntil` приведуть одразу до потрібного абзацу, а не до чотиритисячного файлу, у якому це слово десь є. Ми не вважаємо, що український переклад має замінити англійський оригінал. Хто вільно читає англійською, той і далі читатиме [laravel.com/docs](https://laravel.com/docs) - і правильно робитиме. Але між «прочитати розділ рідною за десять хвилин» і «продиратися через нього годину зі словником» різниця не в зручності, а в тому, чи дочитає людина взагалі. Саме заради цього все й затівалося. Документація жива, поки за нею встигають: тепер вона встигає сама, щодня, без чийогось вечора, витраченого на звірку з апстрімом. Лишається те, що під силу тільки людині, - зробити так, щоб цей текст читався українською, а не перекладеною англійською. Тут ми розраховуємо на вас.