Англійська для розробників Keystatic CMS

Keystatic — це безголовкова система керування вмістом, що підтримується git — вміст зберігається у вигляді файлів markdown або JSON безпосередньо у вашому сховищі, а не у окремій базі даних, а редактори отримують зручний інтерфейс адміністратора. Оскільки це розташоване між «просто редагувати файл markdown» і «повністю хостована CMS», обговорення цього чітко англійською вимагає точності про те, де вміст насправді живе і як зміни протікають. Цей підручник містить словник.

---

Основні поняття

** Система управління вмістом з підтримкою Git ** — система управління вмістом, де кожне зміна записується у ваше сховище git (часто за допомогою відкриття запиту на витягнення), а не зберігається у зовнішній базі даних.

• “Оскільки Keystatic підтримується git, кожна зміна вмісту з’ являється як звичайний запит — ми отримуємо повний історію і перегляд безкоштовно.” *

** Файл налаштувань ** — центральний файл keystatic.config.ts, у якому ви визначаєте збірки, одиниці і поля; це схема для всієї вашої моделі вмісту.

• “Додати нове поле до схеми публікації у блогу можна за допомогою одного рядка у файлі налаштувань — інтерфейс адміністратора Keystatic автоматично оновлюється, щоб показати це поле.” *

** Reader API ** — API типового коду Keystatic створюється для читання вашого вмісту під час збирання, отже, ваш інтерфейс отримує повністю типовий вміст без окремого шару отримання. “Ми використовуємо API читача в getStaticProps — це безпечний тип, тому якщо поле перейменовано в конфігурації, TypeScript позначає кожне місце, яке порушується.”

---

Структура контенту

Collection

** Збірка ** — це набір повторюваних записів вмісту однакової форми, наприклад, статей у блогу або членів команди, кожен з яких зберігається у власному файлі.

“Публікації у блогу є збіркою — кожна публікація є власним файлом markdown у content/posts/, а схема збірки визначає, які поля має мати кожна публікація.”

Singleton

** Singleton ** — це єдиний, одноразовий елемент вмісту, який не має повторюваних елементів, наприклад, параметрів для всього сайту або розділу героя домашньої сторінки.

“Текст героя домашньої сторінки є окремим елементом, а не збіркою — існує тільки один з них, отже, для нього не потрібен перегляд списку у системі адміністрування.”

Field

Поле ** поле ** визначає одну частину структурованих даних у збірці або у окремому елементі — тексті, тексті з розширеними можливостями (полі документа), зображеннях, відносинах або масивах.

“Ми додали поле relatedPosts як зв’ язок до однієї збірки, щоб редактори могли посилатися один на одного з інтерфейсу адміністратора.”

Поле документа

Поле ** document ** є структурованим текстовим редактором Keystatic, який зберігає вміст у вигляді дерева вузлів (а не у вигляді необробленого коду), який можна відтворити у HTML, коді markdown або компонентах React.

• “Поле документа надає редакторам змогу додавати блоки підписів і вбудовувати їх за допомогою інтерфейсу користувача, не знаючи при цьому жодного синтаксису markdown.” *

---

Режими зберігання

** Локальний режим ** — вміст буде прочитано з локальної файлової системи і записано до неї, зазвичай, це відбувається під час розробки.

• “У локальному режимі, збереження статті у інтерфейсі адміністратора записує її безпосередньо до файла markdown на диску — ідеально підходить для локальних розробок.” *

** GitHub режим ** — зміни вмісту проходять через GitHub API, зазвичай відкриваючи запит на витягування, а не затверджуючи безпосередньо в головній гілці. “Ми запускаємо режим GitHub у виробничому режимі — редактори надсилають зміни через адміністратора Keystatic, і він відкриває PR для перегляду перед об’єднанням.”

** Режим хмари ** — додатковий хостований шар над режимом GitHub, який додає зберігання активів і оптимізацію зображень без потреби у вашому власному конвеєрі зображень.

---

Редакційна робота

** Редагування за гілками ** — редактори працюють на окремій гілці git через інтерфейс адміністратора, і зміни досягають виробничого стану лише після злиття цієї гілки (часто через відкритий запит на збирання).

• “Маркетинг створив проект нової копії сторінки призначення на гілки через адміністрування — нічого не було введено доки ми не схвалили і не об’ єднали PR.” *

Поле ** чернетки ** — булеве поле, яке позначає запис як неопублікований, зазвичай використовується для утримання вмісту, який перебуває у процесі збирання, поза межами збирання, доки він не буде готовим.

“Ми перевіряємо поле draft в нашому коді отримання даних і виключаємо все, що все ще позначене як чернетку з виробничої збірки.”

---

Пояснення системи для нетехнічних редакторів

Situation	Phrase
Explaining where content lives	”Every blog post is a file in our repository — Keystatic just gives you a friendly interface so you don’t need to write markdown by hand.”
Explaining the review step	”When you save, it opens a pull request instead of publishing immediately — someone on the dev team reviews it before it goes live.”
Describing a schema change	”We added an ‘excerpt’ field to every post — you’ll see a new box in the admin the next time you edit an existing post.”
Reassuring about content safety	”Because everything is stored in git, we can always see exactly who changed what and revert any accidental edit.”

Поширені помилки

• Назва кожного типу вмісту « колекцією » — singleton призначено для одноразового вмісту, а його використання як колекції збентежить редакторів, які очікують перегляду списку.
• Сказати «база даних CMS» — Keystatic не має бази даних; вміст живе як файли в git, що варто пояснити зацікавленим сторонам, які звикли до традиційних платформ CMS.
• Опис поля документа як « просто markdown » — це структуроване дерево, яке можна відтворити у декількох форматах, а не як сирий текст markdown.

Практичні вправи

1. Поясніть у двох реченнях різницю між збіркою і одиничним елементом редактору вмісту, який не має технічного досвіду.
2. Написати коротку записку для нового редактора вмісту, у якій буде пояснено, що збереження статті призведе до відкриття запиту на витягнення, а не до її негайного опублікування.
3. Створити чернетку повідомлення з описом зміни схеми (нового поля) і описом того, як це поле буде показано у інтерфейсі адміністратора.

Зв’язані ресурси

• Англійська для розробників Sanity CMS
• Англійська для колекцій астрономічного контенту
• Англійська для Contentful CMS Developers

Навигація Nuance: практична англійська для розробників Keystatic

Як розробник, що працює з Keystatic, ви будете взаємодіяти з командами, які в основному спілкуються англійською мовою. Це не просто технічний жаргон; це про ясну, коротку мову, яка забезпечує всіх - від редактора контенту до бекенд-інженера - розуміє і відповідає очікуванням. Одним з найбільших викликів для носіїв мови, які не є рідними носіїв, є переклад технічних концепцій на природно звучачу англійську, особливо при описі структур даних, таких як колекції і синглони. Важливо вийти за рамки буквальних перекладів і зрозуміти, як носії рідної мови вкладають ці ідеї в контекст розвитку.

Часто найзначніші непорозуміння виникають в комунікації навколо переглядів коду або описів PR. Наприклад, замість того, щоб сказати « Ця збірка містить поля singleton », що може звучати надто технічно і, можливо, заплутати когось, хто не знайомий з архітектурою Keystatic, більш природнім підходом буде сказати: « Ця збірка містить окремі частини вмісту — уявіть її як контейнер для окремих статей. » Аналогічно, коли ви пояснюєте API читача, уникайте фраз на зразок « кінцева точка API » і обирайте замість цього « як ми надаємо вміст до фронт- енд », це може значно поліпшити ясність. Під час створення описів PR, зосередьтеся на * якій * зміні було зроблено і * чому *, а не просто на тому, * як *. Наприклад, замість « Оновлено схему поля », спробуйте « Перероблено схему поля « title », щоб включити обов’ язкове поле для покращення якості даних. »

Ключовим є прийняти активний підхід до словникового запасу. Не вагайтеся задати питання, щоб пояснити, навіть якщо ваша початкова фраза не ідеальна. Більшість команд Keystatic оцінять вашу працю і будуть готові допомогти вам удосконалювати вашу мову. Використання таких інструментів, як Grammarly або редактор Hemingway Editor, також може допомогти вам визначити області, де ваші твори могли б бути яснішими і більш короткими. Пам’ятайте, ефективне спілкування - це двостороння дорога; це не тільки передавання інформації, але також активне слухання і розуміння точок зору інших.

Ось приклад використання команди keystatic query для отримання даних зі збірки:

keystatic query --collection myCollection --fields title,body

Це демонструє отримання певних полів ( title, body ) з колекції з назвою myCollection. Вивід буде форматований таким чином, що буде легко зрозумілим для редакторів контенту і розробників, демонструючи силу підходу Keystatic до структурованих даних. Зверніть увагу на такі фрази, як « отримати » і « поля », вони допоможуть вам чітко спілкуватися з вашою командою.