Перевод `docs/api/`¶

Эта папка содержит актуальную версию документации Node.js API. При переводе новых файлов используй docs/archive/api.18/ как локальный эталон терминологии, структуры и оформления, но источником истины всегда считай текущий английский оригинал в docs/api/.

Базовый подход¶

Для каждого файла сначала открой одноименный файл из docs/archive/api.18/, если он существует.
Возьми из архива сложившийся русский каркас: заголовок страницы, формулировки стабильности, стиль списков, подписи табов MJS/CJS, локальные пояснения.
Затем внимательно сверь с новым английским исходником: добавь новые разделы, удали исчезнувшие, обнови формулировки и примеры под текущую версию.
Не копируй архив механически: в api.18 встречаются шероховатости и остатки английского текста, их повторять не нужно.

Что сохранять буквально¶

HTML-комментарии и служебные блоки: , , , .
Имена API, сигнатуры, идентификаторы, anchor id, {: #custom-link}, относительные ссылки и их цели.
Кодовые блоки, CLI-команды, имена модулей node:*, флаги, переменные окружения, коды ошибок.
Строковые литералы и ожидаемый вывод в коде, если перевод меняет смысл примера или ожидаемый результат выполнения.

Что переводить¶

Обычный текст, заголовки, описания, списки, примечания и поясняющие абзацы.
Видимый текст ссылок, если это обычная фраза, а не имя символа/API.
Комментарии внутри примеров, если это именно пояснение для читателя, а не часть проверяемого вывода.

Оформление страницы¶

Если у страницы есть аналог в api.18, сохраняй его локальный формат: frontmatter, русский H1, строку с бейджем версии сразу под заголовком.
Если страницы раньше не было, ориентируйся на ближайший похожий перевод из api.18: короткий description, русский H1, затем ссылка на оригинал.
Для каждого переведенного файла в docs/api/ frontmatter обязателен. Как минимум должны быть заполнены title и description, даже если в текущем английском оригинале frontmatter отсутствует.
Иерархию заголовков, списков, табов и admonition-блоков держи максимально близко к структуре английского файла.
Примеры с MJS/CJS оформляй по локальному шаблону из api.18: через табы === "MJS" / === "CJS" с вложенными блоками ```js, а не через отдельные fence ```mjs / ```cjs.
Если внутри списков или вложенных разделов в архиве используется не таб, а обычный вложенный ```mjs / ```cjs, сохраняй именно такую локальную форму, а не нормализуй её насильно.

Терминология и стиль¶

Пиши естественным техническим русским языком, без буквального машинного калькирования.
Для повторяющихся терминов сначала смотри, как они уже переведены в api.18, и по возможности сохраняй совместимость по всей папке.
Названия типов и сущностей уровня API (Promise, AbortSignal, Worker, EventTarget, CommonJS, ESM) не переводи насильно, если в тексте важнее точное имя, чем русификация.
Если старый перевод звучит явно неестественно или ошибочно, исправляй по английскому оригиналу, а не закрепляй неточность.

Ссылки на типы¶

Записи типов в фигурных скобках, например {Uint8Array}, {Promise}, {Buffer|TypedArray} и аналогичные аннотации параметров/возвращаемых значений, в итоговом docs/api/ должны быть оформлены как настоящие Markdown-ссылки.
Для типовых аннотаций в списках параметров, Returns:/Type:/Extends: и в таблицах используй локальный формат старой документации: [<Uint8Array>](...), [<Promise>](...), [<Buffer | TypedArray>](...).
В обычном тексте без роли типовой аннотации используй ссылку без угловых скобок: [Uint8Array](...), [Promise](...).
Цель ссылки сначала сверяй по одноимённому файлу из docs/archive/api.18/. Если в архиве такого типа или ссылки нет, используй актуальный локальный anchor из текущей документации Node.js, а для встроенных JavaScript/Web-типов — авторитетную внешнюю ссылку, обычно MDN.
Не превращай в типовые ссылки литералы и фрагменты кода вида { signal }, { shell: true }, { recursive: true }, destructuring-объекты и другие объектные литералы, если это не обозначение типа.

Индекс стабильности¶

Используй уже принятые формулировки:

!!!danger "Стабильность: 0 – устарело или набрало много негативных отзывов"
!!!warning "Стабильность: 1 – Экспериментальная"
!!!success "Стабильность: 2 – Стабильная"
!!!note "Стабильность: 3 – Закрыто"

Текст внутри этих блоков бери из сложившегося шаблона архива, если смысл статуса не изменился в новом оригинале.

Финальная проверка¶

Вне кода и служебных комментариев не должно оставаться случайного английского текста.
После перевода проверь, что все внутренние ссылки и anchor-ссылки остались рабочими.
Обнови строку с версией и ссылку на английский оригинал под текущую переводимую ветку документации.
Проверь, что frontmatter присутствует и содержит актуальные title и description.
Готовый файл должен читаться как цельный русский текст, но оставаться структурно близким к официальной документации Node.js.

Перевод docs/api/¶