Automated, scheduled crowdin sync (nodejs#7272)

* chore: add wip action

* feat: automated crowdin sync

* add dry run, workflow_dispatch

* rename token

* add mention of translation deployment

* Update .github/workflows/translations-sync.yml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com>

* docs: clarified our translation flows

* separate translation source upload from download

* Update TRANSLATION.md

Co-authored-by: Michael Esteban <mickel13@gmail.com>
Signed-off-by: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com>

* Update .github/workflows/translations-sync.yml

Co-authored-by: Claudio W <cwunder@gnome.org>
Signed-off-by: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com>

* Update .github/workflows/translations-upload.yml

Co-authored-by: Claudio W <cwunder@gnome.org>
Signed-off-by: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com>

---------

Signed-off-by: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Michael Esteban <mickel13@gmail.com>
Co-authored-by: Claudio W <cwunder@gnome.org>

.github/workflows/translations-pr.yml → .github/workflows/translations-pr-lint-and-format.yml

@@ -1,7 +1,8 @@
 # This Workflow is used to comment on PRs that have changes that touch Translated Files
 # and then comments on their PRs mentioning that they should not do so
+# It also formats incoming content because it is often not adherent to our rules post-translation.
 
-name: Crowdin Checks
+name: Incoming Translation Checks
 
 on:
   pull_request_target:

.github/workflows/translations-sync.yml

@@ -0,0 +1,54 @@
+# This action automates the synchronization of our crowdin translations, so that a human does not need to kick it off from the crowdin UI
+# See translations-upload.yml for automation to upload our source content
+# See translations-pr-lint-and-format.yml for quality control we conduct on ingress of new translations.
+name: Crowdin Download
+
+on:
+  workflow_dispatch: # Allow running when we want to, for events such as urgent translation mistakes or 100% completed languages
+  schedule:
+    - cron: '0 5 * * 5' # At 05:00 on Fridays. This guarantees that we have the 72 hour weekend time to review translations.
+
+# Cancel any runs on the same branch
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  # These permissions required by `crowdin/github-action`
+  contents: write
+  pull-requests: write
+
+jobs:
+  synchronize-with-crowdin:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+        # see all the options at https://github.com/crowdin/github-action
+      - name: crowdin action
+        uses: crowdin/github-action@2d540f18b0a416b1fbf2ee5be35841bd380fc1da # v2.3.0
+        with:
+          # do not upload anything - this is a one-way operation download
+          upload_sources: false
+          upload_translations: false
+          # the rest of this controls how the PR comes in with new translations
+          download_translations: true
+          localization_branch_name: chore/crowdin
+          create_pull_request: true
+          pull_request_title: '[automated]: crowdin sync'
+          pull_request_body: 'New Crowdin translations from the [Node.js Crowdin project](https://crowdin.com/project/nodejs-web)'
+          pull_request_labels: github_actions:pull-request
+          commit_message: 'chore: synced translations from crowdin [skip ci]'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # A numeric ID, found at https://crowdin.com/project/nodejs-web/tools/api
+          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
+          # Created from https://crowdin.com/settings#api-key logged in using nodejs-crowdin-bot
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

.github/workflows/translations-upload.yml

@@ -0,0 +1,41 @@
+# This action automates the upload of our source content to crowdin.
+# See translations-sync.yml for the automation to download new translations on a schedule
+# See translations-pr-lint-and-format.yml for quality control we conduct on ingress of new translations.
+name: Crowdin Upload
+
+on:
+  push:
+    branches: [main]
+
+# Cancel any runs on the same branch
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  upload-to-crowdin:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+        # see all the options at https://github.com/crowdin/github-action
+      - name: crowdin action
+        uses: crowdin/github-action@2d540f18b0a416b1fbf2ee5be35841bd380fc1da # v2.3.0
+        with:
+          # only upload sources, ensuring this is a one-way operation
+          upload_sources: true
+          upload_translations: false
+          download_translations: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # A numeric ID, found at https://crowdin.com/project/nodejs-web/tools/api
+          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
+          # Created from https://crowdin.com/settings#api-key logged in using nodejs-crowdin-bot
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

TRANSLATION.md

@@ -87,3 +87,12 @@ Translation Keys should not be translated during Unit Testing. If your Component
 - Unit Tests should not rely on text, titles, or string bags, as these texts will change arbitrarily and make the test suite fail.
   - In this case, you should test your component by aria-text, or other `aria-*` attributes or even by class names or other artifacts.
 - Visual Regression Testing is recommended to test how different languages and text appear within a Component.
+
+## Deploying Translations
+
+Translations are synced between Crowdin and the repository via GitHub Actions.
+
+- On every push to `main`, we upload any new source content.
+- Via a cron schedule, and as needed manually by a collaborator, we download completed translations.
+
+Incoming translations are linted to ensure they come from crowdin, and are also formatted to adhere to our project settings.

crowdin.yml

@@ -1,8 +1,6 @@
-commit_message: 'chore: synced translations from crowdin [skip ci]'
+project_id_env: 'CROWDIN_PROJECT_ID'
+api_token_env: 'CROWDIN_PERSONAL_TOKEN'
 append_commit_message: false
-pull_request_title: '[automated]: crowdin sync'
-pull_request_labels:
-  - 'github_actions:pull-request'
 files:
   - source: /apps/site/pages/en/**/*.md
     translation: /apps/site/pages/%two_letters_code%/**/%original_file_name%