Как перевести документацию в формате Markdown для разработчиков

Испанский (es/README.md):

Consulta la [Guía de Instalación](./instalacion.md) para instrucciones de configuración.

Revisa la [Referencia de API](./referencia-api.md) para documentación detallada.

Критично:

• Текст ссылок переведён
• URL ссылки обновлён на испанское имя файла
• Испанские файлы должны реально существовать!

Шаг 5: Коммит в Git

git add docs/es/
git commit -m "Add Spanish translation of installation docs"
git push origin main

Обработка особых случаев

1. Комментарии в коде в блоках кода

Стоит ли переводить комментарии?

## Пример

```javascript
// Initialize the application
const app = createApp();

// Start the server on port 3000
app.listen(3000);

**Вариант A: Оставить комментарии кода на английском**
```javascript
// Initialize the application
const app = createApp();

// Start the server on port 3000
app.listen(3000);

Плюсы: Универсальность (разработчики читают комментарии на английском) Минусы: Менее доступно для новичков

Вариант B: Перевести комментарии кода

// Инициализировать приложение
const app = createApp();

// Запустить сервер на порту 3000
app.listen(3000);

Плюсы: Более доступно для разработчиков, не владеющих английским Минусы: Код нельзя просто скопировать-вставить (смешение языков)

Рекомендация: Оставлять английский для примеров продакшн-кода. Переводить для учебных материалов, где понимание важнее копирования.

2. Имена переменных и функций

Никогда не переводить в коде:

// НЕПРАВИЛЬНО - не переводить имена переменных
function obtenerUsuario(idUsuario) {
  return database.buscar(idUsuario);
}

// ПРАВИЛЬНО - код оставлять на английском
function getUser(userId) {
  return database.find(userId);
}

Исключение: Псевдокод или концептуальные примеры

English:

if user is logged in: show dashboard else: redirect to login

Spanish (приемлемо для псевдокода):

si usuario está conectado: mostrar panel sino: redirigir a inicio de sesión

3. Примеры командной строки

Переводить описания, команды НЕТ:

English:
## Generate a New Component

Use the CLI to create a component:

```bash
npx create-component MyComponent

This creates a new component in src/components/MyComponent/.

Spanish:

Generar un Nuevo Componente

Usa la CLI para crear un componente:

npx create-component MyComponent

Esto crea un nuevo componente en src/components/MyComponent/.

**Команды остаются на английском, объяснения переводятся.**

### 4. URL эндпоинтов API

**Оставлять URL без изменений:**

```markdown
English:
### Get User Profile

GET /api/v1/users/:id

Spanish:
### Obtener Perfil de Usuario

GET /api/v1/users/:id

Не: `GET /api/v1/usuarios/:id` (сломает API!)

5. Переменные окружения и конфигурация

Оставлять имена переменных, переводить описания:

English:
Set your API key:

```bash
export API_KEY=your_key_here

Spanish: Configura tu clave de API:

export API_KEY=tu_clave_aqui

API_KEY остаётся на английском (имя переменной окружения). your_key_here → tu_clave_aqui (пример значения, можно переводить).

### 6. Значки и щиты

**Обычное в README.md файлах:**

```markdown
English:
[![Build Status](https://travis-ci.org/user/repo.svg?branch=main)](https://travis-ci.org/user/repo)
[![npm version](https://badge.fury.io/js/awesome-lib.svg)](https://www.npmjs.com/package/awesome-lib)

Spanish: Оставить значки как есть
(Они автоматические от внешних сервисов, независимы от языка)

Или если нужны значки с переведённым текстом:
[![Estado de Construcción](https://travis-ci.org/user/repo.svg?branch=main)](https://travis-ci.org/user/repo)

Обычно: Оставлять английские значки (разработчики ожидают их, статус универсален).

Автоматизация и инструменты

Системы управления переводами для Markdown

1. Crowdin

Возможности:

• Интеграция с GitHub/GitLab
• Поддержка Markdown файлов
• Автоматическое сохранение блоков кода
• Перевод сообществом (контрибьюторы переводят через веб-интерфейс)
• Память переводов

Рабочий процесс:

1. Подключить Crowdin к репозиторию GitHub
2. Crowdin обнаруживает новые/изменённые файлы в docs/en/
3. Переводчики работают через веб-интерфейс Crowdin
4. Crowdin отправляет pull request с переводами
5. Проверка и слияние

Цены: Бесплатно для open-source, $40/месяц+ для коммерческих

2. Lokalise

Возможности:

• Похоже на Crowdin
• Лучший API для автоматизации
• Поддержка Markdown
• CLI инструмент для синхронизации

Рабочий процесс:

# Загрузка исходных файлов
lokalise2 file upload --lang-iso en --file docs/en/README.md

# Скачивание переводов
lokalise2 file download --lang-iso es --dest docs/es/

Цены: $120/месяц+

3. Transifex

Возможности:

• Дружелюбно к open-source
• Поддержка Markdown
• Проверка переводов
• Проверки качества

Цены: Бесплатно для open-source, $30/месяц+ для коммерческих

Рабочие процессы перевода на базе Git

Подход: Отдельные ветки для переводов

# Основная ветка: Документация на английском
git checkout main

# Создание ветки для перевода
git checkout -b translate/spanish

# Перевод файлов
# ...

# Коммит
git add docs/es/
git commit -m "Добавить испанский перевод"

# Пуш и создание PR
git push origin translate/spanish
# Создать pull request на GitHub

Преимущества:

• Переводчики работают независимо
• Процесс проверки через PR
• Отслеживание переводов как функций

Подход: Отслеживание переводов с метаданными Git

en/installation.md:

<!--
Last updated: 2025-01-25
Translation status:
- es: 2025-01-20 (outdated)
- fr: 2025-01-24 (current)
- zh: not started
-->

# Installation
...

Автоматизированный скрипт может проверять эти комментарии и отмечать устаревшие переводы.

Автоматическое обнаружение обновлений переводов

Скрипт для обнаружения устаревших переводов:

import os
from datetime import datetime

def check_translation_status(base_dir="docs"):
    languages = ['en', 'es', 'fr', 'zh']
    base_lang = 'en'

    for lang in languages:
        if lang == base_lang:
            continue

        en_dir = os.path.join(base_dir, base_lang)
        lang_dir = os.path.join(base_dir, lang)

        for file in os.listdir(en_dir):
            if not file.endswith('.md'):
                continue

            en_file = os.path.join(en_dir, file)
            lang_file = os.path.join(lang_dir, file)

            if not os.path.exists(lang_file):
                print(f"⚠️ {lang}/{file} - Не переведено")
                continue

            en_modified = os.path.getmtime(en_file)
            lang_modified = os.path.getmtime(lang_file)

            if en_modified > lang_modified:
                print(f"❌ {lang}/{file} - Устарело (EN обновлен после перевода)")
            else:
                print(f"✅ {lang}/{file} - Актуально")

check_translation_status()

Запуск как GitHub Action:

# .github/workflows/check-translations.yml
name: Check Translation Status

on:
  push:
    paths:
      - 'docs/**'

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check translations
        run: python scripts/check-translations.py
      - name: Comment on PR
        if: github.event_name == 'pull_request'
        run: |
          python scripts/check-translations.py > translation-status.txt
          gh pr comment ${{ github.event.number }} --body-file translation-status.txt

Перевод Markdown с помощью ИИ

AI Trans для документации в markdown:

Возможности:

• Автоматически сохраняет блоки кода
• Сохраняет синтаксис markdown
• Оставляет ссылки нетронутыми
• Быстро (переводит всю документацию за минуты)

Рабочий процесс:

# Перевод README.md с английского на испанский
ai-translator translate \
  --input docs/en/README.md \
  --output docs/es/README.md \
  --source en \
  --target es \
  --format markdown

# Пакетный перевод всех файлов
for file in docs/en/*.md; do
  filename=$(basename "$file")
  ai-translator translate \
    --input "$file" \
    --output "docs/es/$filename" \
    --source en \
    --target es \
    --format markdown
done

Цены: $10 за 1M символов (Standard) или $50 за 10M символов (Business) Бесплатный стартовый пакет: 100,000 символов для тестирования Примеры типичных затрат:

• Маленькая документация (50K символов): $0.50
• Средняя документация (200K символов): $2
• Большая документация (1M символов): $10

Лучшая практика: Перевод ИИ → проверка человеком → коммит

Создание многоязычных сайтов документации

Docusaurus (на базе React)

Настройка:

npx create-docusaurus@latest my-docs classic
cd my-docs

Конфигурация i18n (docusaurus.config.js):

module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr', 'zh'],
    localeConfigs: {
      en: { label: 'English' },
      es: { label: 'Español' },
      fr: { label: 'Français' },
      zh: { label: '中文' }
    }
  },
  // ...
};

Структура директорий:

docs/
├── intro.md (English default)
├── installation.md
i18n/
├── es/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           ├── intro.md (Spanish)
│           └── installation.md
├── fr/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           ├── intro.md (French)
│           └── installation.md

Сборка:

# Сборка всех языков
npm run build

# Сборка конкретного языка
npm run build -- --locale es

Результат: Автоматический переключатель языков, многоязычный сайт, оптимизированный для SEO.

VuePress (на базе Vue)

Конфигурация i18n (.vuepress/config.js):

module.exports = {
  locales: {
    '/': {
      lang: 'en-US',
      title: 'My Documentation',
      description: 'Documentation for awesome library'
    },
    '/es/': {
      lang: 'es-ES',
      title: 'Mi Documentación',
      description: 'Documentación para awesome library'
    },
    '/fr/': {
      lang: 'fr-FR',
      title: 'Ma Documentation',


      description: 'Документация для awesome library'
    }
  },
  themeConfig: {
    locales: {
      '/': {
        selectText: 'Языки',
        label: 'English',
        nav: [
          { text: 'Руководство', link: '/guide/' },
          { text: 'API', link: '/api/' }
        ]
      },
      '/es/': {
        selectText: 'Языки',
        label: 'Español',
        nav: [
          { text: 'Руководство', link: '/es/guide/' },
          { text: 'API', link: '/es/api/' }
        ]
      }
    }
  }
};

**Структура директорий:**

docs/ ├── README.md (английский) ├── guide/ │ └── installation.md ├── es/ │ ├── README.md (испанский) │ └── guide/ │ └── installation.md └── fr/ ├── README.md (французский) └── guide/ └── installation.md

### MkDocs (на основе Python)

**Установка с плагином i18n:**

```bash
pip install mkdocs mkdocs-static-i18n

mkdocs.yml:

plugins:
  - i18n:
      default_language: en
      languages:
        en: English
        es: Español
        fr: Français
      material_alternate: true

nav:
  - Главная: index.md
  - Установка: installation.md
  - Справочник API: api.md

Структура директорий:

docs/
├── index.md (английский по умолчанию)
├── index.es.md (испанский)
├── index.fr.md (французский)
├── installation.md
├── installation.es.md
├── installation.fr.md

Сборка:

mkdocs build

Результат: Создаёт site/ с переключателем языков.

Развёртывание на GitHub Pages

Развёртывание многоязычного сайта Docusaurus:

# .github/workflows/deploy.yml
name: Развёртывание документации

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Установка зависимостей
        run: npm install
      - name: Сборка сайта
        run: npm run build
      - name: Развёртывание на GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

Доступ:

• Английский: https://youruser.github.io/yourrepo/
• Испанский: https://youruser.github.io/yourrepo/es/
• Французский: https://youruser.github.io/yourrepo/fr/

Лучшие практики и типичные ошибки

Лучшие практики

1. Начните с наиболее важных страниц

Приоритет:
1. README.md (первое, что видят пользователи)
2. Установка/Начало работы (барьер для внедрения)
3. Справочник API (необходим разработчикам)
4. Руководство по вкладу (для международных участников)

Отложите на потом:
- Журналы изменений (менее критично)
- Устаревшая документация
- Внутренние заметки разработчиков

2. Ведите руководство по стилю перевода

# Руководство по переводу - Испанский

## Терминология
- "library" → "biblioteca" (не "librería", что означает книжный магазин)
- "framework" → оставлять как "framework" (широко понятно)
- "deploy" → "desplegar" (не "implementar")

## Тон
- Используйте формальное "usted" для технической документации
- Используйте неформальное "tú" для руководств/туториалов
- Будьте краткими (испанский в среднем на 20% длиннее английского)

## Код
- Никогда не переводите блоки кода
- Оставляйте технические термины на английском, если они широко используются

3. Версионируйте переводы

README.md:
<!--
Translation: Spanish
Source version: v2.5.0
Translated: 2025-01-25
Translator: @username
-->

# Instalación
...

Это помогает отслеживать отставание переводов.

4. Поощряйте вклад сообщества

## Вклад в переводы

Мы приветствуем переводы! Чтобы внести вклад:

1. Форкните этот репозиторий
2. Создайте директорию `docs/[код-языка]/`
3. Переведите файлы из `docs/en/`
4. Создайте pull request

Руководство по переводу: [TRANSLATION.md](./TRANSLATION.md)

Типичные ошибки

Ошибка 1: Перевод URL и путей к файлам

❌ НЕПРАВИЛЬНО:
[See installation](./instalación.md)
# Файл не существует (содержит акцентированные символы)

✅ ПРАВИЛЬНО:
[See installation](./instalacion.md)
# Файл: instalacion.md (без акцентов в имени файла)

Ошибка 2: Нарушение относительных ссылок

Английский: docs/en/guide.md ссылается на: ../assets/image.png
Испанский: docs/es/guia.md должен ссылаться на: ../assets/image.png (тот же путь!)

Если переводчик напишет: ./assets/image.png (сломано!)

Ошибка 3: Забывание alt-текста для изображений

![](./screenshot.png)

Должно быть:
![Dashboard screenshot](./screenshot.png)

Испанский:
![Captura de pantalla del panel](./screenshot.png)

Alt-текст важен для доступности!

Ошибка 4: Несогласованная терминология

Страница 1: "servidor" (сервер)
Страница 3: "server" (оставлен на английском)
Страница 5: "servidor" снова

Выберите один вариант и придерживайтесь его! Используйте глоссарий.

Измерение успеха

Метрики для отслеживания

1. Использование документации по языкам

Google Analytics (сайт документации):
- Трафик по языкам (es, fr, de и т.д.)
- Время на странице (выше = лучше понимание)
- Коэффициент отказов (ниже для документации на родном языке)

Пример:
Документация на английском: 70% пользователей
Документация на испанском: 15% пользователей (но растёт!)
Документация на французском: 10% пользователей
Другие: 5%

2. Инсайты GitHub

GitHub Issues:
- Количество issues, поданных на каждом языке
- Время ответа на issues на неанглийских языках

Pull Requests:
- Вклады от стран, где не говорят на английском
- После испанских docs: +40% вкладов от разработчиков LATAM

Stars/Forks:
- Отслеживание роста после релизов переводов

3. Рост сообщества

Discord/Slack:
- Активность каналов по конкретным языкам
- Вопросы на родных языках

Stack Overflow:
- Вопросы с тегами вашей библиотеки на разных языках

4. Загрузки npm/PyPI по географии

npm download stats by country:
До китайского перевода:
- Китай: 5% загрузок

После китайского перевода:
- Китай: 22% загрузок (рост в 4.4 раза!)

Затраты и ROI

Инвестиции в перевод

Небольшая open-source библиотека (5000 слов документации):

Профессиональный перевод:

Перевод: 5000 × $0.08 = $400 на язык
Ревью: $100
Итого на язык: $500

3 языка (es, fr, zh): $1500

Перевод с помощью ИИ:

Перевод ИИ (AI Trans): 5000 слов × 6 символов в среднем = 30 000 символов = $0.30
Технический ревьюер: 5 часов × $75 = $375
Итого на язык: $375.30

3 языка: $1126 (экономия 25%)

Сообществом (бесплатно, но медленнее):

Настройка Crowdin: Бесплатно для open-source
Переводы: Бесплатно (волонтёры сообщества)
Время на ревью: Ваше время (5-10 часов на язык)

3 языка: $0 денежных затрат, 15-30 часов временных вложений

ROI для Open-Source проектов

ROI не всегда денежный — это рост сообщества:

Метрики до испанских/китайских переводов:
- Ежемесячные загрузки npm: 50 000
- Звёзды GitHub: 2500
- Контрибьюторы: 40 (в основном США/Европа)

Через 6 месяцев после переводов:
- Ежемесячные загрузки npm: 120 000 (рост 140%)
- Звёзды GitHub: 6800 (рост 172%)
- Контрибьюторы: 95 (55 новых из LATAM/Азии)

Ценность сообщества: Бесценна
Затраты: $1500 за ИИ-перевод + ревью

Инструменты и ресурсы

Инструменты для перевода

AI Trans

• Автоматически сохраняет форматирование markdown
• Сохраняет блоки кода нетронутыми (никогда не переводит код)
• Поддерживает структуру ссылок
• $10 за 1M символов (Standard) или $50 за 10M символов (Business)
• Бесплатный стартовый пакет 100K символов
• Поддержка 57 языков

DeepL API

• Высокое качество для европейских языков
• Поддержка Markdown с предобработкой
• $25 за миллион символов + подписка $5.49/месяц

Google Cloud Translation

• 133 языка
• Хорошо для широкого покрытия языками
• $20 за миллион символов
• Не поддерживает markdown (требуется предобработка)

Линтинг и валидация Markdown

markdownlint

• Проверяет синтаксис markdown
• Обеспечивает единообразное форматирование
• CLI и плагины для редакторов

npm install -g markdownlint-cli
markdownlint docs/es/*.md

markdown-link-check

• Проверяет все ссылки в markdown-файлах
• Ловит сломанные относительные ссылки

npm install -g markdown-link-check
markdown-link-check docs/es/README.md

Генераторы сайтов документации

Docusaurus (React)

• Лучше всего для: разработчиков React, современные SPA docs
• Встроенная i18n
• Бесплатно

VuePress (Vue.js)

• Лучше всего для: разработчиков Vue
• Простая настройка
• Бесплатно

MkDocs (Python)

• Лучше всего для: Python-проектов
• Минимальная настройка
• Бесплатно

GitBook

• Лучше всего для: неразработчиков (GUI-редактор)
• Хостинговое решение
• Бесплатно для open-source

Заключение

Перевод документации в формате markdown — одно из наиболее значимых вкладов в создание глобального сообщества разработчиков. Делая ваш проект доступным на нескольких языках, вы открываете доступ к нему для миллиардов разработчиков, не говорящих на английском, и способствуете разнообразному международному сотрудничеству.

Ключевые выводы:

• Сохраняйте блоки кода, синтаксис markdown и структуру ссылок
• Используйте отдельные директории для каждого языка для чистой организации
• Автоматизируйте синхронизацию переводов с Git-воркфлоу
• Используйте ИИ-перевод + человеческое ревью для экономичного качества
• Создавайте многоязычные сайты с Docusaurus, VuePress или MkDocs
• Отслеживайте переводы с помощью метаданных и автоматизированных проверок
• Поощряйте вклады сообщества для устойчивого перевода

Современные ИИ-инструменты вроде AI Trans могут снизить затраты на перевод на 70-90%, сохраняя все критические элементы markdown, такие как блоки кода, ссылки и форматирование. Оптимальный workflow: ИИ переводит начальную документацию (минуты, а не недели), технические ревьюеры обеспечивают точность и согласованность, затем сообщество помогает поддерживать обновления.

Типичные затраты на перевод документации:

• Маленький проект (50K символов): $0.50 с AI Trans против $400 человеческого перевода
• Средний проект (200K символов): $2 с AI Trans против $1600 человеческого перевода
• Большой проект (1M символов): $10 с AI Trans против $8000 человеческого перевода

Экономия времени: 95%+ (минуты против недель)

Будьте вы автором маленькой утилитарной библиотеки или крупного open-source фреймворка, переведённая документация устраняет языковые барьеры и приглашает разработчиков со всего мира в ваш проект.

Готовы перевести вашу документацию? Начните переводить свои markdown-документы с помощью движка перевода AI Trans, сохраняющего код, и охватите глобальную аудиторию разработчиков.