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

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

#I. Локализация системы

#1. Перевод интерфейса системы и плагинов

#1.1 Область перевода

Это относится только к локализации интерфейса системы NocoBase и плагинов и не охватывает другой пользовательский контент (например, таблицы данных или блоки Markdown).

#1.2 Обзор контента локализации

NocoBase использует Git для управления контентом локализации. Основной репозиторий: https://github.com/nocobase/nocobase/tree/main/locales

Каждый язык представлен JSON-файлом, названным в соответствии с его кодом языка (например, de-DE.json, fr-FR.json). Структура файла организована по модулям плагинов с использованием пар «ключ-значение» для хранения переводов. Например:

{
  // Клиентский плагин
  "@nocobase/client": {
    "(Fields only)": "(Fields only)",
    "12 hour": "12 hour",
    "24 hour": "24 hour"
    // ...другие пары «ключ-значение»
  },
  "@nocobase/plugin-acl": {
    // Пары «ключ-значение» для этого плагина
  }
  // ...другие модули плагинов
}

При переводе, пожалуйста, постепенно преобразуйте его в структуру, подобную следующей:

{
  // Клиентский плагин
  "@nocobase/client": {
    "(Fields only)": "(Только поля - переведено)",
    "12 hour": "12-часовой формат",
    "24 hour": "24-часовой формат"
    // ...другие пары «ключ-значение»
  },
  "@nocobase/plugin-acl": {
    // Пары «ключ-значение» для этого плагина
  }
  // ...другие модули плагинов
}

#1.3 Тестирование и синхронизация перевода

• После завершения перевода, пожалуйста, протестируйте и убедитесь, что все тексты отображаются правильно. Мы также выпустили плагин для проверки перевода — найдите Locale tester в магазине плагинов. После установки скопируйте содержимое JSON из соответствующего файла локализации в git-репозитории, вставьте его внутрь и нажмите «ОК», чтобы проверить, вступил ли перевод в силу.

• После отправки системные скрипты автоматически синхронизируют контент локализации с репозиторием кода.

#1.4 Плагин локализации NocoBase 2.0

Примечание: Этот раздел находится в разработке. Плагин локализации для NocoBase 2.0 имеет некоторые отличия от версии 1.x. Подробности будут предоставлены в будущем обновлении.

#II. Локализация документации (NocoBase 2.0)

Документация для NocoBase 2.0 управляется в новой структуре. Исходные файлы документации находятся в основном репозитории NocoBase:

https://github.com/nocobase/nocobase/tree/next/docs

#2.1 Структура документации

Документация использует Rspress в качестве генератора статических сайтов и поддерживает 22 языка. Структура организована следующим образом:

docs/
├── docs/
│   ├── en/                    # Английский (исходный язык)
│   ├── cn/                    # Упрощенный китайский
│   ├── ja/                    # Японский
│   ├── ko/                    # Корейский
│   ├── de/                    # Немецкий
│   ├── fr/                    # Французский
│   ├── es/                    # Испанский
│   ├── pt/                    # Португальский
│   ├── ru/                    # Русский
│   ├── it/                    # Итальянский
│   ├── tr/                    # Турецкий
│   ├── uk/                    # Украинский
│   ├── vi/                    # Вьетнамский
│   ├── id/                    # Индонезийский
│   ├── th/                    # Тайский
│   ├── pl/                    # Польский
│   ├── nl/                    # Голландский
│   ├── cs/                    # Чешский
│   ├── ar/                    # Арабский
│   ├── he/                    # Иврит
│   ├── hi/                    # Хинди
│   ├── sv/                    # Шведский
│   └── public/                # Общие ресурсы (изображения и т. д.)
├── theme/                     # Пользовательская тема
├── rspress.config.ts          # Конфигурация Rspress
└── package.json

#2.2 Рабочий процесс перевода

1. Синхронизация с английским источником: Все переводы должны основываться на английской документации (docs/en/). При обновлении английской документации переводы должны быть обновлены соответствующим образом.

2. Стратегия ветвления:

   • Используйте ветку develop или next в качестве эталона для последнего английского контента.
   • Создайте свою ветку перевода из целевой ветки.

3. Структура файлов: Каждый языковой каталог должен зеркально отражать структуру английского каталога. Например:

   docs/en/get-started/index.md    →    docs/ru/get-started/index.md
   docs/en/api/acl/acl.md          →    docs/ru/api/acl/acl.md

#2.3 Участие в переводе

1. Сделайте форк репозитория: https://github.com/nocobase/nocobase
2. Клонируйте свой форк и переключитесь на ветку develop или next.
3. Перейдите в каталог docs/docs/.
4. Найдите языковой каталог, в который вы хотите внести вклад (например, ru/ для русского).
5. Переведите markdown-файлы, сохраняя ту же структуру файлов, что и в английской версии.
6. Протестируйте изменения локально:

   cd docs
   yarn install
   yarn dev
7. Отправьте Pull Request в основной репозиторий.

#2.4 Руководство по переводу

• Соблюдайте единообразие форматирования: Сохраняйте ту же структуру markdown, заголовки, блоки кода и ссылки, что и в источнике.
• Сохраняйте frontmatter: Оставляйте любой YAML frontmatter в верхней части файлов без изменений, если только он не содержит переводимый контент.
• Ссылки на изображения: Используйте те же пути к изображениям из docs/public/ — изображения являются общими для всех языков.
• Внутренние ссылки: Обновляйте внутренние ссылки, чтобы они указывали на правильный языковой путь.
• Примеры кода: Как правило, примеры кода не следует переводить, но комментарии внутри кода переводить можно.

#2.5 Конфигурация навигации

Структура навигации для каждого языка определена в файлах _nav.json и _meta.json внутри каждого языкового каталога. При добавлении новых страниц или разделов обязательно обновите эти конфигурационные файлы.

#III. Локализация веб-сайта

Страницы веб-сайта и весь контент хранятся по адресу: https://github.com/nocobase/website

#3.1 Начало работы и справочные ресурсы

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

• Английский: https://github.com/nocobase/website/tree/main/src/pages/en
• Китайский: https://github.com/nocobase/website/tree/main/src/pages/cn
• Японский: https://github.com/nocobase/website/tree/main/src/pages/ja

Глобальные модификации стилей находятся по адресам:

• Английский: https://github.com/nocobase/website/blob/main/src/layouts/BaseEN.astro
• Китайский: https://github.com/nocobase/website/blob/main/src/layouts/BaseCN.astro
• Японский: https://github.com/nocobase/website/blob/main/src/layouts/BaseJA.astro

Локализация глобальных компонентов веб-сайта доступна по адресу: https://github.com/nocobase/website/tree/main/src/components

#3.2 Структура контента и метод локализации

Мы используем смешанный подход к управлению контентом. Контент и ресурсы на английском, китайском и японском языках регулярно синхронизируются из системы CMS и перезаписываются, в то время как другие языки можно редактировать напрямую в локальных файлах. Локальный контент хранится в каталоге content, организованном следующим образом:

/content
  /articles        # Статьи блога
    /article-slug
      index.md     # Английский контент (по умолчанию)
      index.cn.md  # Китайский контент
      index.ja.md  # Японский контент
      metadata.json # Метаданные и другие свойства локализации
  /tutorials       # Обучающие материалы
  /releases        # Информация о релизах
  /pages           # Некоторые статические страницы
  /categories      # Информация о категориях
    /article-categories.json  # Список категорий статей
    /category-slug            # Детали отдельной категории
      /category.json
  /tags            # Информация о тегах
    /article-tags.json        # Список тегов статей
    /release-tags.json        # Список тегов релизов
    /tag-slug                 # Детали отдельного тега
      /tag.json
  /help-center     # Контент справочного центра
    /help-center-tree.json    # Структура навигации справочного центра
  ....

#3.3 Руководство по переводу контента

• О переводе контента Markdown

1. Создайте новый языковой файл на основе файла по умолчанию (например, из index.md в index.ru.md).
2. Добавьте локализованные свойства в соответствующие поля в JSON-файле.
3. Соблюдайте единообразие структуры файлов, ссылок и путей к изображениям.

• Перевод контента JSON Многие метаданные контента хранятся в JSON-файлах, которые обычно содержат многоязычные поля:

{
  "id": 123,
  "title": "English Title",       // Английский заголовок (по умолчанию)
  "title_cn": "中文标题",          // Китайский заголовок
  "title_ja": "日本語タイトル",    // Японский заголовок
  "description": "English description",
  "description_cn": "中文描述",
  "description_ja": "日本語の説明",
  "slug": "article-slug",         // URL-путь (обычно не переводится)
  "status": "published",
  "publishedAt": "2025-03-19T12:00:00Z"
}

Примечания к переводу:

1. Соглашение об именовании полей: Поля перевода обычно используют формат {исходное_поле}_{код_языка}.

   • Например: title_ru (русский заголовок), description_ru (русское описание).

2. При добавлении нового языка:

   • Добавьте версию с соответствующим языковым суффиксом для каждого поля, требующего перевода.
   • Не изменяйте значения исходных полей (таких как title, description и т. д.), так как они служат контентом для языка по умолчанию (английского).

3. Механизм синхронизации CMS:

   • Система CMS периодически обновляет контент на английском, китайском и японском языках.
   • Система будет обновлять/перезаписывать контент только для этих трех языков (некоторые свойства в JSON) и не будет удалять языковые поля, добавленные другими участниками.
   • Например: если вы добавили русский перевод (title_ru), синхронизация CMS не затронет это поле.

#3.4 Настройка поддержки нового языка

Чтобы добавить поддержку нового языка, вам необходимо изменить конфигурацию SUPPORTED_LANGUAGES в файле src/utils/index.ts:

export const SUPPORTED_LANGUAGES = {
  en: {
    code: 'en',
    locale: 'en-US',
    name: 'English',
    default: true
  },
  cn: {
    code: 'cn',
    locale: 'zh-CN',
    name: 'Chinese'
  },
  ja: {
    code: 'ja',
    locale: 'ja-JP',
    name: 'Japanese'
  },
  // Пример добавления нового языка:
  ru: {
    code: 'ru',
    locale: 'ru-RU',
    name: 'Russian'
  }
};

#3.5 Файлы макетов и стили

Для каждого языка требуются соответствующие файлы макетов:

1. Создайте новый файл макета (например, для русского языка создайте src/layouts/BaseRU.astro).
2. Вы можете скопировать существующий файл макета (например, BaseEN.astro) и перевести его.
3. Файл макета содержит переводы для глобальных элементов, таких как меню навигации, футеры и т. д.
4. Обязательно обновите конфигурацию переключателя языков, чтобы он правильно переключался на вновь добавленный язык.

#3.6 Создание языковых каталогов страниц

Создайте независимые каталоги страниц для нового языка:

1. Создайте папку с кодом языка в каталоге src (например, src/ru/).
2. Скопируйте структуру страниц из других языковых каталогов (например, из src/en/).
3. Обновите содержимое страниц, переведя заголовки, описания и текст на целевой язык.
4. Убедитесь, что страницы используют правильный компонент макета (например, .layout: '@/layouts/BaseRU.astro').

#3.7 Локализация компонентов

Некоторые общие компоненты также требуют перевода:

1. Проверьте компоненты в каталоге src/components/.
2. Обратите особое внимание на компоненты с фиксированным текстом (такие как панели навигации, футеры и т. д.).
3. Компоненты могут использовать условный рендеринг для отображения контента на разных языках:

{Astro.url.pathname.startsWith('/en') && <p>English content</p>}
{Astro.url.pathname.startsWith('/cn') && <p>中文内容</p>}
{Astro.url.pathname.startsWith('/ru') && <p>Русский контент</p>}

#3.8 Тестирование и проверка

После завершения перевода проведите тщательное тестирование:

1. Запустите веб-сайт локально (обычно с помощью yarn dev).
2. Проверьте, как все страницы отображаются на новом языке.
3. Убедитесь, что функция переключения языков работает правильно.
4. Убедитесь, что все ссылки указывают на страницы правильной языковой версии.
5. Проверьте адаптивные макеты, чтобы переведенный текст не нарушал дизайн страницы.

#IV. Как начать перевод

Если вы хотите внести свой вклад в перевод NocoBase на новый язык, выполните следующие действия:

После завершения перевода отправьте Pull Request в NocoBase. Новые языки появятся в конфигурации системы, что позволит вам выбрать язык для отображения.

#Документация NocoBase 1.x

Руководство по переводу NocoBase 1.x см. по адресу:

https://docs-cn.nocobase.com/welcome/community/translations