Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
171 lines (127 loc) · 5.77 KB

CONTRIBUTING.md

File metadata and controls

171 lines (127 loc) · 5.77 KB
Raw

Gramps Web Docs Contributing Guide

Thanks for helping to improve the Gramps Web documentation! This guide will help you get started with contributing.

Finding your way around

The documentation pages are written in Markdown and stored in the docs/en directory. Each page on grampsweb.org corresponds to a .md file in this directory.

The navigation structure is defined in the mkdocs.yml file at the root of the repository. This file controls how the pages are organized and displayed in the sidebar.

There is a automated translation service implemented, which will translate all new/changed files in docs/en to the other languages.

Making changes

To make changes to the documentation, simply change the relevant Markdown files in the docs/en directory and submit a pull request.

If you are proficient with git, you can clone the repository, make your changes locally, and push them to your fork. If you're not familiar with git, you can also edit files directly on Github using the web interface.

Adding new pages

To add a new page to the documentation, create a new Markdown file in the docs/en directory and add it to the mkdocs.yml file under the appropriate section. Make sure to follow the existing structure and formatting. If you can, also add the translations for the navigation under mkdocs.yml .

Adding translations

The documentation currently supports:

  1. English (en) - Default
  2. Deutsch (de) - German
  3. Français (fr) - French
  4. Español (es) - Spanish
  5. 简体中文 (zh) - Simplified Chinese
  6. Tiếng Việt (vi) - Vietnamese
  7. Türkçe (tr) - Turkish
  8. Русский (ru) - Russian
  9. Português (pt) - Portuguese
  10. 日本語 (ja) - Japanese
  11. Dansk (da) - Danish
  12. Suomi (fi) - Finnish
  13. Italiano (it) - Italian
  14. Українська (uk) - Ukrainian

The translations of the actual .md files are managed automatically using OpenAI GPT-4o-mini. The navigation (under mkdocs.yml) and home.html need to be translated manually.

Adding a new language

To add a new language to the documentation:

  1. Update the configuration in translate.py and add the Language under LANGUAGE_NAMES:

    CONFIG = {
    "translation": {
        "target_languages": ["de", "fr", "es"],  # Add your language code
        ...
    }
}

# Language names for prompting and display
LANGUAGE_NAMES = {
    "de": "German",
    "fr": "French",
    "es": "Spanish",
    "it": "Italian",
    "en": "English"
}

  2. Add the language to MkDocs in mkdocs.yml and add the navigation translations:

    plugins:
  - i18n:
      languages:
        - locale: es
          name: Español
          build: true
          nav_translations:
            Home: Inicio
            Features: Características
            # ... add all navigation translations

  3. Extend github workflow in .github\workflows\translate.yml:

     - name: Check for translation changes
        id: check-changes
        if: steps.changed-files.outputs.changed == 'true'
        run: |
          # Check if any translations were actually changed

          # ADD NEW LANGUAGES HERE
          if git diff --quiet docs/de/ docs/fr/ docs/es/ docs/zh-hans/ docs/vi/ docs/uk/ docs/tr/ docs/ru/ docs/pt/ docs/ja/; then
            echo "No translation changes"
            echo "has_changes=false" >> $GITHUB_OUTPUT
          else
            echo "Translation changes detected"
            echo "has_changes=true" >> $GITHUB_OUTPUT
          fi

      - name: Commit translations
        if: steps.check-changes.outputs.has_changes == 'true'
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"

          # ADD NEW LANGUAGES HERE
          git add docs/de/ docs/fr/ docs/es/ docs/zh-hans/ docs/vi/ docs/uk/ docs/tr/ docs/ru/ docs/pt/ docs/ja/

          # Create commit message with list of translated files
          COMMIT_MSG="Auto-translate documentation\n\nTranslated files:\n"
          for file in ${{ steps.changed-files.outputs.files }}; do
            COMMIT_MSG="${COMMIT_MSG}- ${file}\n"
          done

          git commit -m "$(echo -e "$COMMIT_MSG")"

  4. Add homepage translations in overrides/translations/home.yml:

    hero:
  es:
    title: "Gramps Web"
    description: "..."
    demo_button: "..."
learn_more:
  es:
    title: "..."
    # ... add all homepage translations

  5. Run the translation:

    python translate.py --lang es

Translating content

All English source files are in docs/en/. When you modify an English file, translations are automatically generated via GitHub Actions. For manual translation:

# Set up your OpenAI API key
cp .env.example .env
# Add your API key to .env

# Translate specific file
python translate.py --file user-guide/blog.md --lang de

# Translate all files
python translate.py --lang all

Previewing changes

If you are just editing or adding Markdown to a page, there may not be a need to preview your changes. However, if you are making significant changes or adding new pages, you can preview your changes locally by following these steps:

  1. Install the necessary dependencies:
python -m pip install -r requirements.txt
  1. Run the MkDocs development server:
python -m mkdocs serve -a localhost:8211
  1. Open your web browser and go to http://localhost:8211 to see your changes live. The web server will automatically reload when you make changes to the Markdown files.