Помощь с переводом

Помощь с переводом

Спасибо за ваш интерес к переводу документации TrucklineMP! Это руководство объясняет, как участвовать в переводе, каких стандартов мы придерживаемся и как отправить готовую работу.

Зачем переводить?

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

Поддерживаемые в данный момент языки

Локаль	Язык	Статус
en	English	Исходный язык, всегда заполнен
pl	Polski (Polish)	Принимаются переводы от сообщества
de	Deutsch (German)	Принимаются переводы от сообщества
fr	Français (French)	Принимаются переводы от сообщества

Вы не ограничены польским языком. Вы можете переводить документацию на любой язык, которым свободно владеете. Если вашего языка нет в списке выше, следуйте инструкциям из раздела “Добавление нового языка” ниже и свяжитесь с командой проекта, чтобы мы добавили нужную локаль.

---

Как устроены переводы

Документация TrucklineMP создана на базе Astro Starlight, фреймворка со встроенной поддержкой интернационализации (i18n).

Структура файлов

Переводы хранятся в папках конкретных локалей внутри каталога src/content/docs/:

src/content/docs/
├── index.mdx                     # Английская главная страница
├── guides/
│   ├── verified-vtc-program.mdx  # Английское руководство
│   └── ...
└── pl/                           # Папка польской локали
    ├── index.mdx                 # Польская главная страница
    └── guides/
        ├── verified-vtc-program.mdx  # Polish translation
        └── ...

Структура URL-адресов

• Английский: https://docs.trucklinemp.com/guides/verified-vtc-program/
• Польский: https://docs.trucklinemp.com/pl/guides/verified-vtc-program/
• Немецкий: https://docs.trucklinemp.com/de/guides/verified-vtc-program/
• Французский: https://docs.trucklinemp.com/fr/guides/verified-vtc-program/

Переключатель языков в правом верхнем углу позволяет пользователям переключаться между доступными языками.

---

Что можно переводить?

1. Содержимое руководств

Все .mdx файлы внутри каталога src/content/docs/guides/ доступны для перевода. Каждому английскому руководству должен соответствовать аналогичный файл в папке целевой локали.

2. Главная страница

Приветственная страница index.mdx также должна быть переведена, чтобы встречать пользователей на их языке.

3. Ярлыки бокового меню

Названия пунктов бокового меню настраиваются в файле astro.config.mjs и поддерживают переводы:

sidebar: [
  {
    label: 'VTC Programs',
    items: [
      {
        slug: 'guides/verified-vtc-program',
        label: 'Verified VTC Program',
        translations: {
          pl: 'Zweryfikowany Program VTC',
        },
      },
    ],
  },
],

При переводе добавьте название на вашем языке в объект translations.

4. Элементы интерфейса

Некоторые системные подписи Starlight (например, “На этой странице”, “Редактировать страницу”, “Поиск”) обрабатываются встроенной системой переводов Starlight. Если язык не поддерживается фреймворком в полной мере, мы можем добавить пользовательские переводы интерфейса через файл конфигурации.

---

Перед началом работы

Требования

• Аккаунт на GitHub
• Базовое понимание синтаксиса Markdown и MDX
• Свободное владение как английским, так и целевым языком
• Знание терминологии TrucklineMP (VTC, конвой и т. д.)

Рекомендуемые инструменты

• Удобный текстовый редактор (VS Code, Cursor и др.)
• Расширение для предварительного просмотра Markdown
• Установленный локально клиент Git (либо работа через веб-интерфейс GitHub)

---

Процесс перевода

Шаг 1: Сделайте форк репозитория

1. Перейдите в репозиторий документации на GitHub
2. Нажмите кнопку Fork в правом верхнем углу
3. Склонируйте свой форк на локальный компьютер или работайте через веб-интерфейс GitHub

Шаг 2: Настройте проект (Необязательно)

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

# Клонирование вашего форка
git clone https://github.com/ВАШ_НИКНЕЙМ/docs.git
cd docs

# Установка зависимостей
npm install

# Запуск сервера разработки
npm run dev

Сайт будет доступен по адресу http://localhost:4321.

Шаг 3: Выберите руководство для перевода

Проверьте текущий статус готовности и выберите руководство, которое ещё не было переведено или требует обновления. Приоритетные страницы:

1. Verified VTC Program
2. Partnered VTC Program
3. VTC General Settings
4. Profile Settings
5. Account Security

Шаг 4: Создайте файл перевода

1. Найдите исходный английский файл (например, src/content/docs/guides/verified-vtc-program.mdx)
2. Создайте аналогичный файл в папке целевой локали (например, src/content/docs/pl/guides/verified-vtc-program.mdx)
3. Скопируйте метаданные из шапки и переведите основной текст

Шаг 5: Сохраняйте структуру метаданных

Метаданные в шапке должны сохранять исходную структуру. Переводить можно исключительно их значения:

---
title: Verified VTC Program Rules
description: Complete guide to the Truckline Verified VTC Program — how to apply, requirements, and rules for maintaining verified status.
---

Пример для польского языка:

---
title: Zasady Programu Zweryfikowanych VTC
description: Pełny przewodnik po Programie Zweryfikowanych VTC Truckline — jak aplikować, wymagania i zasady utrzymania statusu zweryfikowanego.
---

Шаг 6: Переведите пункты бокового меню

Откройте astro.config.mjs и добавьте переводы для тех руководств, над которыми вы работали:

{
  slug: 'guides/verified-vtc-program',
  label: 'Verified VTC Program',
  translations: {
    pl: 'Zweryfikowany Program VTC',
  },
},

Шаг 7: Проверьте свою работу

Запустите сервер разработки и перейдите на переведённую страницу:

http://localhost:4321/pl/guides/verified-vtc-program/

Убедитесь, что:

• Весь контент переведён
• Ссылки работают корректно
• Форматирование сохранено
• Изображения отображаются правильно
• Подписи в боковом меню переведены

Шаг 8: Отправьте Pull Request

1. Закоммитьте изменения с понятным сообщением:

   docs(pl): translate verified VTC program guide

2. Отправьте коммит в свой форк
3. Откройте Pull Request в ветку main оригинального репозитория
4. Опишите, что именно вы перевели, и добавьте примечания для проверяющих

---

Стандарты перевода

Точность

• Переводите смысл, а не слово в слово
• Сохраняйте техническую точность
• Оставляйте форматирование, ссылки и общую структуру идентичными оригиналу

Тон

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

Терминология

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

Английский	Вариант для польского
Virtual Trucking Company (VTC)	Wirtualna Firma Transportowa (VTC)
Verified	Zweryfikowany
Partnered	Partnerski
Member	Członek
Role	Rola
Recruitment	Rekrutacja
Profile	Profil
Two-Factor Authentication	Uwierzytelnianie Dwuskładnikowe

Код и URL-адреса

Строго запрещается переводить:

• URL-адреса
• Пути к файлам
• Фрагменты кода
• Адреса электронной почты
• Ссылки-приглашения в Discord
• Названия технических параметров

Ссылки

• Внутренние ссылки должны вести на переведённую версию страницы (если она существует)
• Пример: /guides/verified-vtc-program/ → /pl/guides/verified-vtc-program/
• Внешние ссылки должны оставаться без изменений

Изображения

• Не переводите названия файлов изображений
• Альтернативный текст должен быть переведён
• Если скриншот содержит текст, рассмотрите возможность сделать локализованную версию изображения

---

Контрольный список качества

Перед отправкой перевода убедитесь, что:

• Метаданные сохранены и переведены
• Все заголовки переведены
• Весь основной текст переведён
• Ссылки указывают на правильную локаль
• Блоки кода и URL-адреса оставлены без изменений
• Ярлыки бокового меню обновлены в astro.config.mjs
• Страница корректно отображается на локальном сервере разработки
• Нет сломанной разметки или ошибок Markdown
• Терминология едина во всём тексте

---

Обновление переводов

Когда исходный английский текст обновляется, переводы могут устаревать. Помогайте поддерживать их в актуальном состоянии:

1. Отслеживайте изменения в исходных английских файлах
2. Вносите аналогичные правки в переведённые файлы
3. При необходимости обновляйте метаданные в шапке
4. Отправляйте Pull Request с чётким описанием проделанной работы

---

Добавление нового языка

Вы можете переводить документацию на любой язык. Если ваш язык ещё не поддерживается, вы можете добавить его сами.

Шаги

1. Свяжитесь с командой в Discord, чтобы сообщить, что вы работаете над новым языком
2. Мы добавим локаль в astro.config.mjs
3. Создайте папку локали внутри каталога src/content/docs/ (например, de/ для немецкого)
4. Переведите основные руководства
5. Отправьте Pull Request

Нет жёсткого правила касательно того, сколько страниц нужно перевести для внедрения языка, но мы рекомендуем начать как минимум с:

• Главная страница (index.mdx)
• Verified VTC Program
• Partnered VTC Program
• VTC General Settings
• Profile Settings

Настройка локали

Новые локали регистрируются в файле astro.config.mjs:

locales: {
  root: {
    label: 'English',
    lang: 'en',
  },
  pl: {
    label: 'Polski',
    lang: 'pl',
  },
  de: {
    label: 'Deutsch',
    lang: 'de',
  },
  fr: {
    label: 'Français',
    lang: 'fr',
  },
},

Убедитесь, что используете правильный языковой тег BCP 47 для вашей локали.

---

Частые ошибки

Перевод URL-адресов

❌ /pl/przewodniki/zweryfikowany-program-vtc/
✅ /pl/guides/verified-vtc-program/

Забытые метаданные

❌ Отсутствие title или description
✅ Полностью заполненный frontmatter на целевом языке

Непоследовательная терминология

❌ Использование слова «weryfikacja» в одном месте и «zweryfikowanie» в другом
✅ Единый термин на протяжении всего руководства

Поломка синтаксиса Markdown

❌ Удаление символов # из заголовков или повреждение структуры таблиц
✅ Строгое сохранение всей разметки Markdown

---

Получение помощи

Если у вас возникли вопросы по поводу перевода:

• Discord: https://discord.gg/trucklinemp
• GitHub Issues: Откройте задачу в репозитории документации
• Обсуждение Pull Request: Оставляйте комментарии в существующих PR для получения обратной связи

---

Признание заслуг

Имена переводчиков будут указаны в документации. Спасибо, что помогаете сделать TrucklineMP доступным для каждого!