Skip to content

README: stop teaching the patterns we removed everywhere else #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pavel-te wants to merge 1 commit into
base: main
Choose a base branch
from
Open

README: stop teaching the patterns we removed everywhere else #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 111 additions & 57 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,22 +301,33 @@ The exit code is the CI-facing verdict, so it reports what actually happened rat

## CI/CD Usage

> **On GitHub Actions, do not do any of this by hand.** Use
> [`OnTheGoSystems/ptc-action`](https://github.com/OnTheGoSystems/ptc-action) —
> it vendors this script at a fixed version, SHA-pins its own dependencies, and
> opens the translation PR for you. The recipe is in
> [GitHub Actions](#github-actions) below. Everything in this section is for
> pipelines that run the CLI directly.

### Pinning the CLI version

Pipelines download the script from a **pinned release tag**, not a moving branch,
so a push to `main` can never change what your build runs:

```bash
curl -fsSL https://raw.githubusercontent.com/OnTheGoSystems/ptc-cli/v1.0.0/ptc-cli.sh -o ptc-cli.sh
curl -fsSL https://raw.githubusercontent.com/OnTheGoSystems/ptc-cli/v1.0.3/ptc-cli.sh -o ptc-cli.sh
```

Use `v1.0.0` to pin an exact release, or the floating `v1` tag to pick up
Use `v1.0.3` to pin an exact release, or the floating `v1` tag to pick up
backward-compatible updates automatically. The `ptc init` command scaffolds the
pinned URL for you.

**Verify the download** against the SHA256 checksum published on the
[release page](https://github.com/OnTheGoSystems/ptc-cli/releases):

```
87efed00bd9345b9a4d5fb1972d8d53525246f6a2a4e6a48ae7d20d67e41362a ptc-cli.sh # v1.0.3
```

```bash
# macOS
shasum -a 256 ptc-cli.sh
Expand All @@ -329,64 +340,42 @@ the server can attribute traffic to a specific release.

### GitHub Actions

Add PTC_API_TOKEN to the repository secrets (Settings -> Secrets and variables -> Actions -> New repository secret).
Ensure to turn on the "Allow GitHub Actions to create and approve pull requests" permission in the repository settings (Settings -> Actions -> General -> Workflow permissions).
Add `PTC_API_TOKEN` to the repository secrets (Settings → Secrets and variables →
Actions → New repository secret), and turn on "Allow GitHub Actions to create and
approve pull requests" (Settings → Actions → General → Workflow permissions).

Then use the action — it vendors this CLI at a fixed version, so nothing is
fetched at job time:

```yaml
name: Process Translation Files
name: Translate
on:
workflow_dispatch: # Manual trigger
push:
branches: [main]
paths: ['locales/en.json'] # trigger on SOURCE changes only → loop-safe
workflow_dispatch: {}

permissions:
contents: write
pull-requests: write

jobs:
process-translations:
translate:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write

steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Setup PTC CLI
run: |
curl -fsSL https://raw.githubusercontent.com/OnTheGoSystems/ptc-cli/v1.0.0/ptc-cli.sh -o ptc-cli.sh
chmod +x ptc-cli.sh

- name: Process translations with PTC CLI
env:
PTC_API_TOKEN: ${{ secrets.PTC_API_TOKEN }}
run: |
./ptc-cli.sh \
--config-file .ptc/config.yml \
--verbose

- name: Clean up temporary files
run: |
rm -f ptc-cli.sh

- name: Create Pull Request with translations
if: success()
uses: peter-evans/create-pull-request@v5
- uses: actions/checkout@v7
- uses: OnTheGoSystems/ptc-action@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
commit-message: "🌐 Update translations via PTC CLI"
title: "🌐 Update translations from PTC"
body: |
## 🌐 Translation Update

This PR contains new translations processed by PTC CLI.

**Triggered by:** ${{ github.event_name }}
**Branch:** ${{ github.ref_name }}
**Commit:** ${{ github.sha }}

---
*Auto-generated by GitHub Actions*
delete-branch: true
api-token: ${{ secrets.PTC_API_TOKEN }}
create-pr: true
```

Sample `.ptc/config.yml` file:
`api-token` is the only input you have to pass: a `.ptc-config.yml` committed at
the repository root is picked up on its own, and with no config at all the action
runs `ptc init` and uses what it detects. Full input list in the
[action README](https://github.com/OnTheGoSystems/ptc-action#inputs-github-action).

Sample `.ptc-config.yml` (this is what `ptc init` writes):

```yaml
source_locale: en
Expand All @@ -397,21 +386,86 @@ files:
output: src/locales/{{lang}}.json
```

<details>
<summary>Running the CLI directly instead of the action</summary>

The action exists because a hand-rolled job has to get four things right that it
gets wrong by default: pinning the CLI (not `main`), keeping the token out of
`argv`, SHA-pinning the PR action rather than a movable tag, and not
re-triggering itself. If you still want the steps:

```yaml
- uses: actions/checkout@v7

- name: Setup PTC CLI
run: |
curl -fsSL https://raw.githubusercontent.com/OnTheGoSystems/ptc-cli/v1.0.3/ptc-cli.sh -o ptc-cli.sh
echo "87efed00bd9345b9a4d5fb1972d8d53525246f6a2a4e6a48ae7d20d67e41362a ptc-cli.sh" | sha256sum -c -
chmod +x ptc-cli.sh

- name: Process translations
env:
PTC_API_TOKEN: ${{ secrets.PTC_API_TOKEN }} # env, never --api-token
run: ./ptc-cli.sh --config-file .ptc-config.yml --verbose

- name: Create Pull Request with translations
uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
with:
token: ${{ secrets.GITHUB_TOKEN }}
branch: ptc/translations # stable branch → re-runs update ONE PR
commit-message: "chore(i18n): update translations via PTC"
title: "Update translations from PTC"
delete-branch: true
```

</details>

### GitLab CI

`ptc init` prints this job for you, pinned to the CLI version you ran it with.
Store `PTC_API_TOKEN` as a **masked** CI/CD variable (Settings → CI/CD →
Variables) — it is read from the environment, never placed on the command line.

```yaml
process_translations:
ptc-translate:
stage: deploy
image: alpine:3.22
rules:
- if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
before_script:
- apk add --no-cache bash curl git jq
script:
- curl -fsSL https://raw.githubusercontent.com/OnTheGoSystems/ptc-cli/v1.0.3/ptc-cli.sh -o ptc-cli.sh
- chmod +x ptc-cli.sh
- ./ptc-cli.sh -c config.yml -v
variables:
PTC_API_TOKEN: "$CI_PTC_API_TOKEN"
only:
- merge_requests
- main
- ./ptc-cli.sh --config-file .ptc-config.yml
- |
if ! git diff --quiet; then
git config user.email "ci@ptc"
git config user.name "PTC Translate"
git checkout -B ptc/translations
git add -A
git commit -m "chore(i18n): update translations via PTC [skip ci]"
git push -o merge_request.create \
-o merge_request.target="$CI_DEFAULT_BRANCH" \
-o merge_request.title="Update translations from PTC" \
-f "https://gitlab-ci-token:${PTC_GIT_PUSH_TOKEN:-$CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" HEAD:ptc/translations
fi
```

**The push needs a token that may write to the repository.** `CI_JOB_TOKEN` can,
but only if a maintainer enables Settings → CI/CD → Job token permissions →
*"Allow Git push requests to the repository"* (GitLab 18.4+, off by default).
Otherwise set `PTC_GIT_PUSH_TOKEN` to a project access token with the
`write_repository` scope, also masked.

Loop-safe twice over: the job only runs on a push to the default branch — the
translation push targets `ptc/translations`, so it cannot re-trigger — and the
commit carries `[skip ci]`, the only skip token GitLab honours.

There is no GitLab CI/CD Catalog component. `include: component:` is resolved
against the reader's **own** instance, so a component we publish on one server
can never be included from gitlab.com or from a self-hosted install.

### Additional Translation Files

When using YAML configuration, you can specify additional files to be generated (useful for WordPress):
Expand Down