Проектируем документацию для людей
Почему дизайн по-прежнему важен в эпоху ИИ и какими принципами оформления документации мы руководствуемся, чтобы избавить читателя от лишнего информационного шума.
Kevin Liu, Taylor Fang
Kevin Liu
Публикации
Показано 6 из 16
Что делает агент Locadex?
Locadex — это AI-агент General Translation, который интернационализирует ваш код и переводит контент в вашем репозитории GitHub. Его автоматизации запускаются при открытии пул-реквеста, при пуше коммита или вручную, а каждое изменение поступает в виде пул-реквеста.
Kevin Liu, Kevin Wu
Как форматировать числа, даты и валюты для каждой локали?
Форматируйте каждое значение при рендеринге страницы с учётом локали читателя с помощью JavaScript Intl API и не включайте его в переводимое предложение. Компоненты General Translation <Num>, <Currency>, <DateTime> и <RelativeTime> делают и то и другое внутри <T>, поэтому один перевод подходит для любого значения.
Kevin Liu, Kevin WuКак проверять и редактировать переводы?
Сравнивайте каждый перевод с источником и другими локалями и исправляйте то, что звучит неправильно. В General Translation переводы редактируются на странице «Переводы» в панели управления, а ход проверки отслеживается с помощью меток и комментариев. При следующем запуске перевода Locadex, AI-агент платформы, переносит правки в пул-реквест.
Kevin Liu, Kevin WuКак поддерживать переводы в актуальном состоянии при каждом развёртывании?
Запускайте перевод как этап конвейера перед каждой сборкой для рабочей среды — тогда новые тексты попадут в то же развёртывание, что и сами изменения, уже переведёнными. В CLI gt от General Translation для этого служит команда npx gt translate, которая использует ключ API проекта и идентификатор проекта, сохранённые как секреты CI.
Kevin Liu, Kevin WuКак перевести строки вне JSX?
Пропускайте каждую строку, которая не является дочерним элементом JSX (например, плейсхолдер или константу в области видимости модуля), через функцию перевода в том месте, где выполняется её рендеринг. Такую функцию возвращает хук useGT от General Translation, а msg вместе с useMessages переводит константы, определённые вне компонента.
Kevin Liu, Kevin WuКак перевести сайт документации на Mintlify?
Создайте переведённую копию каждой страницы в отдельной папке для каждого языка и добавьте все языки в навигацию docs.json. AI-агент General Translation под названием Locadex открывает пул-реквест, который добавляет переведённые страницы и навигацию для каждого языка, а затем переводит последующие изменения.
Kevin Liu, Kevin Wu