Перевод docs/api/

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

Ответы в чате

• Отвечай максимально кратко; без объяснений.

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

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

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

• Имена API, сигнатуры, идентификаторы, anchor id, {: #custom-link}, относительные ссылки и их цели.
• Кодовые блоки, CLI-команды, имена модулей node:*, флаги, переменные окружения, коды ошибок.
• Строковые литералы и ожидаемый вывод в коде, если перевод меняет смысл примера или ожидаемый результат выполнения.
• Во внутренних ссылках можно переводить только видимый текст. Сам fragment после # должен в точности совпадать с авто-slug заголовка или с явным {#anchor-id} в строке этого заголовка (см. MD051 ниже); не русифицируй fragment «по смыслу» русского заголовка.

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

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

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

• Если у страницы есть аналог в api.18, сохраняй его локальный формат: frontmatter, русский H1, строку с бейджем версии сразу под заголовком.
• Если страницы раньше не было, ориентируйся на ближайший похожий перевод из api.18: короткий description, русский H1, затем ссылка на оригинал.
• Для каждого переведенного файла в docs/api/ frontmatter обязателен. Как минимум должны быть заполнены title и description, даже если в текущем английском оригинале frontmatter отсутствует.
• Иерархию заголовков, списков, табов и admonition-блоков держи максимально близко к структуре английского файла.
• Если у заголовка есть явный anchor id, оформляй его инлайн в той же строке заголовка: ## Заголовок {#anchor-id}.
• Для якорей заголовков в docs/api/ используй локальный стиль инлайновых id через {#anchor-id}. Не вставляй отдельные HTML-якоря вида <a id="anchor-id"></a> и не выноси связанный с заголовком anchor на отдельную строку.
• MD051 (link-fragments): markdownlint сопоставляет внутренние ссылки #... с заголовками по авто-slug в духе GitHub (для русского текста fragment получается закодированным и не совпадает с «английскими» id из оригинала Node.js) и с явными id вида {#anchor-id} в той же строке, что и ## / ###. Суффикс pymdown {: #id} в эту проверку не входит: ссылка на, например, #event-close при заголовке только с {: #event-close} или без явного id будет ошибкой MD051. Чтобы сохранить привычный fragment как в англ. доке и пройти линтер, пиши: ### Русский текст {#event-close} (а не полагайся только на {: #event-close} в конце строки).
• Ссылочные определения в конце файла ([идентификатор]: url и ссылки вида [текст][идентификатор]) не оставляй: всегда заменяй на инлайновые ссылки [текст](url) в том месте текста, где они нужны.
• Примеры с 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>`](...).
• Тип any оформляй по тому же правилу: не [<any>](...), а только [`<any>`](https://developer.mozilla.org/docs/Web/JavaScript/Data_structures#Data_types). То же касается массивов и производных форм, например [`<any[]>`](...).
• Если видимый текст ссылки содержит угловые скобки <...>, оборачивай весь текст ссылки в инлайн-код, чтобы Markdown не воспринимал его как HTML. Это правило действует и для простых типов вроде [`<any>`](...), и для составных типов вроде [`<Promise<void>>`](...).
• В обычном тексте без роли типовой аннотации используй ссылку без угловых скобок: [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-ссылки остались рабочими.
• Если заголовок переведён на русский, отдельно проверь, что ссылки на него по-прежнему указывают на исходный anchor id, а не на автоматически придуманный русский fragment.
• Если нужно сохранить старый или нестандартный fragment для совместимости ссылок, добавляй его через инлайновый {#...} у самого заголовка, а не через отдельный HTML-anchor.
• Обнови строку с версией и ссылку на английский оригинал под текущую переводимую ветку документации.
• Проверь, что frontmatter присутствует и содержит актуальные title и description.
• Готовый файл должен читаться как цельный русский текст, но оставаться структурно близким к официальной документации Node.js.

Комментарии