content-sync

A GitHub Action to synchronize translatable content from Scientific Python projects to their corresponding translation repositories.

This action automates the process of copying source content (e.g., HTML or Markdown files) from an upstream project repository into a dedicated translations repository. It is designed to work seamlessly with the Scientific Python Translations infrastructure and integrates with Crowdin for managing translations.

---

📦 Features

• Automated Content Syncing: Periodically syncs specified folders from the source repository to the translations repository.
• Customizable Configuration: Supports specifying source repository, folder paths, branches, and more.
• Integration with Crowdin: Prepares content in a format suitable for Crowdin translation workflows.
• GitHub Actions Workflow: Easily integrate into existing CI/CD pipelines using GitHub Actions.

🚀 Getting Started

Prerequisites

• A GitHub repository containing the source content you wish to translate.
• A separate translations repository set up to receive and manage translated content part of the Scientific Python Translations organization.
• GitHub Actions enabled on the translations repository.

⚙️ Usage

Basic Example

Here's a sample GitHub Actions workflow that uses the content-sync action to sync content from the main branch of the numpy/numpy.org repository:

name: Sync Content

on:
  schedule:
    - cron: "0 12 * * MON" # Every Monday at noon
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Sync Pandas Content
        uses: Scientific-Python-Translations/content-sync@main
        with:
          source-repo: "numpy/numpy.org"
          source-path: "content/en/"
          source-ref: "main"
          translations-repo: "Scientific-Python-Translations/numpy.org-translations"
          translations-path: "content/"
          translations-source-path: "content/en/"
          translations-ref: "main"
          auto-merge: "false"
          # These are provided by the Scientific Python Project and allow
          # automation with bots
          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
          passphrase: ${{ secrets.PASSPHRASE }}
          token: ${{ secrets.TOKEN }}

Inputs

Input	Required	Default	Description
source-repo	✅	—	GitHub repo with the source content (e.g., numpy/numpy.org).
source-path	✅	—	Path to the content folder with respect to the source repo root (e.g., content/en/)
source-ref	❌	main	Branch or tag to sync from.
translations-repo	✅	—	Target repo for translated content (e.g., Scientific-Python-Translations/numpy.org-translations).
translations-path	✅	—	Path to the folder where the translations will be synced with respect to translation repo root (e.g., content/).
translations-source-path	✅	—	Path to the folder where the source strings will be synced with respect to translation repo root (e.g., content/en/).
translations-ref	❌	main	Branch of the target translations repo.
auto-merge	❌	false	Whether to auto-merge the created pull request.

🛠️ Setup Instructions

1. Create a Translations Repository: Set up a separate repository to hold the translated content. You can use the translations-cookiecutter as template for the repository.

2. Configure Crowdin: Integrate your translations repository with Crowdin to manage translations. Ensure that the translations paths are set up correctly for Crowdin.

3. Set Up the Workflow: Add the above GitHub Actions workflow to your source repository (e.g., .github/workflows/sync-content.yml). This is created automatically if you used the translations-cookiecutter.

Important: Any content that can be translated needs to live inside translations-source-path.

🔄 How It Works

1. Checkout Source Repository: The action checks out the specified source-repo and source-ref.

2. Copy Content: It copies the contents of source-path from the source repository.

3. Checkout Translations Repository: The action checks out the specified translations-repo and translations-ref.

4. Place Synced Content: It places the copied content into the specified translations-source-path within the translations repository.

5. Commit and PR Creation: The action commits the changes with the specified and creates a Pull Request with signed commits and performs and automatic merge if the option is enabled.

🤖 Bot Activity

All synchronization pull requests and automated commits are performed by the dedicated bot account: @scientificpythontranslations

This ensures consistent and traceable contributions from a centralized automation identity. If you need to grant permissions or configure branch protection rules, make sure to allow actions and PRs from this bot.

🙌 Community & Support

• Join the Scientific Python Discord and visit the #translation channel
• Browse the Scientific Python Translations documentation
• Visit the content-sync and translations-sync Github actions.

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.

📄 License

This project is licensed under the MIT License.