Как перевести техническую документацию, не нарушая код

TABLE OF CONTENTS

Техническая документация не прощает ошибок: одна сломанная ограда кода, заполнитель или якорь могут нарушить сборки, запутать читателей или вызвать сбои при копировании и вставке. Это руководство предлагает вам повторяемый, безопасный рабочий процесс для перевода технической документации с уверенностью — сохраняя код в целости и документацию готовой к выпуску.

Для кого это предназначено: технические писатели, разработчики и переводчики, работающие с документацией для разработчиков, руководствами по API и содержимым в стиле README.

Краткий обзор:

Понять, что никогда не должно переводиться (код, ключи, токены)
Сохранить синтаксис, который анализируют инструменты (ограды, скобки, якоря)
Проверить структурированные данные и ссылки после правок
Использовать автоматизацию для выявления проблем перед выпуском

Подготовка к переводу

Инвентаризация типов контента

Markdown (заголовки, ссылки, таблицы), блоки кода, встроенный код
Структурированные данные: фрагменты JSON/YAML/TOML и конфигурационные файлы
Скриншоты, диаграммы и встроенные визуальные элементы

Определение непереводимых токенов

Пути к файлам, названия пакетов, импорты, имена API, флаги CLI, переменные окружения
Заполнители и переменные: {count}, %s, $HOME, {{token}}
Имена файлов и расширения: config.yaml, .env, .md, .json

Установление направляющих для согласованности

Глоссарий/терминологическая база для терминов области и названий продуктов
Руководство по стилю: тон, формальность, пунктуация, правила заголовков
Стратегия якорей/слагов для каждого региона (стабильные против локализованных)

Настройка безопасной проверки

Сборка на стадии для проверки Markdown/ссылок после каждой партии
Парсеры/линтеры для JSON/YAML/TOML
Проверка ссылок и валидатор якорей в CI

Основные меры предосторожности

Не переводите код, идентификаторы, ключи, имена файлов, переменные окружения или флаги.
Сохраняйте пунктуацию и синтаксис, которые анализируют инструменты (обратные кавычки, скобки, вертикальные черты).
Сохраняйте значимые пробелы: отступы для структуры кода и списков.
Используйте огражденные блоки кода с языковым тегом последовательно (js, bash и т.д.).
Предпочитайте примечания переводчика вместо “исправления” логики кода — вместо этого сообщайте о проблемах ответственным лицам.

Блоки кода и встроенный код

You are trained on data up to October 2023.

Сохраняйте ограждения кода, подсказки языка и содержимое без изменений. Переводите только комментарии и строки, читаемые человеком, если это необходимо.

Пример — безопасный против небезопасного:

// БЕЗОПАСНО: Только комментарий локализован
// Получает токен пользователя
import { getToken } from "@acme/sdk";
const token = await getToken();

// НЕБЕЗОПАСНО: Не переводите идентификаторы/импорты/названия пакетов
// import { obtenirJeton } from "@acme/sdk"; // ❌

Встроенный код должен оставаться дословным:

Хорошо: «Запустите npm install -g acme-cli, а затем acme login.»
Плохо: «Запустите npm install -g acme-cli, а затем acme connexion.» ❌

Проверяйте возможность копирования-вставки: Если читатель копирует любой фрагмент, он должен работать так же, как в исходнике.

Заполнители и формат сообщений ICU

Сохраняйте заполнители точно, включая пробелы и пунктуацию вокруг них.

# Не изменяйте токены или пробелы
echo "Обработка {count} файлов"   # ✅
echo "Обработка { count } файлов" # ❌ добавляет пробелы внутри фигурных скобок

Пример ICU:

{count, plural,
  =0 {Нет сообщений}
  one {# сообщение}
  other {# сообщений}
}

Не изменяйте ключи (count, one, other).
Переводите только читаемые человеком части («сообщение», «сообщений»).
Не вводите и не удаляйте категории множественного числа без указаний продукта.

Ссылки, якоря и слаги

Сохраняйте синтаксис ссылок Markdown и стратегию разрешения согласованными.

[Прочитайте руководство по API](/api/getting-started)  
[Смотрите раздел конфигурации](#configuration)

Переводите текст ссылки, если необходимо; будьте осторожны с URL и якорями.
Якоря: либо сохраняйте стабильные якоря для всех локалей, либо генерируйте якоря для каждой локали и обновляйте ссылки соответственно.
Убедитесь, что относительные пути и якоря хэша все еще разрешаются после перевода.
Не переводите расширения файлов или параметры запроса.

Структурированные данные (JSON/YAML/TOML)

Переводите только значения — никогда ключи, типы или структуру. Всегда повторно анализируйте после редактирования.

JSON:

{
  "title": "Руководство пользователя",
  "cta": "Начать",
  "limits": { "max": 5, "unit": "запросов/секунда" }
}

Ключи, такие как title, cta, limits, max, должны оставаться неизменными.
Числа, логические значения и null остаются как типы, а не слова.

YAML (следите за сложенными скалярами):

note: >
  Строки объединяются в один абзац.
  Сохраняйте отступы и маркеры без изменений.

Сохраняйте кавычки, экранирование, отступы и завершающие запятые (где применимо).

Имена файлов, CLI и API

Не переводите имена файлов, названия пакетов, конечные точки или флаги CLI.
Сохраняйте чувствительность к регистру точно так же, как в источнике (например, --DryRun против --dry-run).
Сохраняйте команды дословно; добавляйте пояснения, если существуют различия, специфичные для локали.

# Правильно
kubectl get pods --namespace default

# Неправильно (флаг переведен) ❌
kubectl get pods --nom-espace defaut

Особенности Markdown

Таблицы: сохраняйте вертикальные линии и выравнивание; не разбивайте столбцы.

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

Предупреждения/заметки: сохраняйте маркеры, используемые вашим инструментом.
Встроенный HTML: избегайте изменения тегов/атрибутов.
Сноски: сохраняйте идентификаторы и порядок.
Умные кавычки: предпочитайте прямые кавычки в контексте кода.

Визуальные элементы и доступность

Локализуйте альтернативный текст по значению, а не по содержанию пикселей.
Предпочитайте скриншоты, не зависящие от локали (подчеркивайте интерфейс, а не язык), или предоставляйте наборы для каждой локали.
Сохраняйте исходные файлы диаграмм (например, Mermaid) в синхронизации между локалями.
Избегайте встроенного текста в изображениях; выносите подписи и метки.

SEO и метаданные

Переводите заголовки, описания и заголовки с использованием ключевых слов, соответствующих локали.
Сохраняйте канонические URL и hreflang в соответствии с правилами сайта.
Не переводите ключи мета/свойств или ключи JSON‑LD.
Согласуйте слаги с вашей стратегией якорей, чтобы избежать 404 ошибок.

Рабочий процесс и автоматизация

Используйте рабочий процесс CAT/LLM, который сохраняет участки кода и теги.
Закрепите терминологию с помощью глоссария и списка “не переводить”.
Добавьте хуки pre-commit для линтинга Markdown и проверки JSON/YAML.
Запустите проверку ссылок и валидатор якорей для каждого PR.
Изменения группируйте в небольшие, поддающиеся обзору части и отслеживайте различия.

Предлагаемые инструменты (адаптируйте под ваш стек):

Линтинг Markdown и проверка ссылок в CI
Шаг парсинга JSON/YAML для выявления синтаксических регрессий
Пакеты регулярных выражений для сканирования заполнителей и числовых форматов

QA и Валидация

Запустите эти проверки перед слиянием:

Соберите сайт для выявления синтаксических ошибок: pnpm build
Проверка типов/контента (коллекции контента Astro): pnpm astro check
Предварительный просмотр и тестирование ключевых страниц: pnpm preview
Проверьте, компилируются ли или запускаются ли примеры кода (где применимо)
Запустите проверку ссылок и якорей; исправьте все 404 или сломанные хэши

Общие ошибки

Случайный перевод ключей/заполнителей.
Нарушение ограждений кода или труб таблиц.
Локализация путей к файлам, флагов или имен API.
Изменение заголовков без обновления якорных ссылок.
Введение умных кавычек внутри кода или JSON.

Приложение: Быстрые контрольные списки

Предварительная проверка (5 пунктов)

Глоссарий и список “не переводить” готовы
Токены/заполнители определены и защищены
Стратегия якорей/слагов подтверждена
Цели ссылок сопоставлены (внутренние против внешних)
Доступна сборка для тестирования

Безопасность примеров кода (5 пунктов)

Ограждения и подсказки языков сохранены
Идентификаторы/импорты не затронуты; комментарии локализованы только
Заполнители и кавычки сохранены
Тест копирования-вставки пройден
Устаревшие фрагменты отмечены для поддерживающих

Структурированные данные (5 пунктов)

Ключи и типы не затронуты
Кавычки/экранирование/отступы сохранены
Числа и булевы значения остаются как типы
Парсер/линтер проходит локально
Различия проверены на случайные изменения ключей

Связанное чтение