Skip to content

Commit 9ac18a9

Browse files
edouardedouard
committed
Default to safe push with --merge --ignore-missing
Pushes are now additive by default — they add or update keys on WTI but never delete. This prevents accidentally obsoleting keys that were added on WTI but are missing from stale local files. - Change push_options default to '--merge --ignore-missing' - Fix api_key description to avoid GitHub Actions parse error - Add Safe Sync Model and Recommended Workflow sections to README - Add target file push example and destructive override to EXAMPLES
1 parent e7d7470 commit 9ac18a9

4 files changed

Lines changed: 73 additions & 15 deletions

File tree

‎README.md‎

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,6 @@ jobs:
2525
steps:
2626
- uses: actions/checkout@v4
2727
- uses: webtranslateit/github-action@v1
28-
with:
29-
api_key: ${{ secrets.WTI_API_KEY }}
3028
env:
3129
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
3230
```
@@ -35,11 +33,11 @@ jobs:
3533
3634
| Input | Description | Default |
3735
|-------|-------------|---------|
38-
| `api_key` | WTI API key. Overrides value in `.wti`. Use `${{ secrets.WTI_API_KEY }}`. | — (read from `.wti`) |
36+
| `api_key` | WTI API key. If not provided, the key is read from the `.wti` config file. | — (read from `.wti`) |
3937
| `config` | Path to the `.wti` config file | `.wti` |
4038
| `upload_sources` | Push source files to WTI | `true` |
4139
| `upload_translations` | Also push target (translated) files | `false` |
42-
| `push_options` | Extra flags for `wti push` (e.g. `--merge --minor`) | `''` |
40+
| `push_options` | Flags for `wti push` (see [Safe Sync Model](#safe-sync-model)) | `'--merge --ignore-missing'` |
4341
| `download_translations` | Pull translations from WTI | `true` |
4442
| `pull_options` | Extra flags for `wti pull` (e.g. `--force --locale fr`) | `''` |
4543
| `push_translations` | Commit & push downloaded translations | `true` |
@@ -92,13 +90,62 @@ permissions:
9290
pull-requests: write
9391
```
9492

93+
## Safe Sync Model
94+
95+
By default, source files are pushed with `--merge --ignore-missing`:
96+
97+
- **`--merge`** — new keys in the file are added to WTI; existing translations are not overwritten.
98+
- **`--ignore-missing`** — keys present on WTI but absent from the uploaded file are left alone (not obsoleted).
99+
100+
This means pushes are **additive** — they can add or update keys, but never delete. Translations done on WTI are never lost by a push.
101+
102+
### Why this matters
103+
104+
Without these flags, pushing a source file that is missing keys (e.g. because a translator added them on WTI and the developer hasn't pulled yet) would silently obsolete those keys and lose their translations.
105+
106+
### Target file uploads
107+
108+
Target file push (`upload_translations: true`) uploads translated files alongside source files. Use this with caution: target file uploads **can overwrite translations** done on WTI, because they replace the full translation content. Only enable this if you are sure your local translations are up to date.
109+
110+
```yaml
111+
- uses: webtranslateit/github-action@v1
112+
with:
113+
upload_translations: true
114+
push_options: '--merge --ignore-missing'
115+
env:
116+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
117+
```
118+
119+
### Overriding the defaults
120+
121+
If you want the old destructive behaviour (keys missing from the file get obsoleted), clear the default flags:
122+
123+
```yaml
124+
- uses: webtranslateit/github-action@v1
125+
with:
126+
push_options: ''
127+
env:
128+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
129+
```
130+
131+
## Recommended Workflow
132+
133+
1. Developer adds keys and source text (e.g. English) in code, commits, pushes to the default branch.
134+
2. The action pushes the source file to WTI (safe merge — adds new keys, never deletes).
135+
3. Translators translate on the WTI web interface.
136+
4. The action pulls translations back and opens a pull request.
137+
5. The team merges the PR to get translations into the codebase.
138+
139+
Developers can run `wti pull` locally to preview translations during development, but should never run `wti push` — the action is the sole writer to WTI.
140+
95141
## Advanced Examples
96142

97143
See [docs/EXAMPLES.md](docs/EXAMPLES.md) for more workflow recipes:
98144

99145
- Upload only on push
100146
- Scheduled download every 6 hours
101-
- Push with `--merge --ignore-missing`
147+
- Destructive push (override safe defaults)
148+
- Push target files (translations)
102149
- Pull specific locales
103150
- Custom config path
104151
- Using the key from `.wti` directly

‎action.yml‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,7 @@ branding:
99
inputs:
1010
# Authentication
1111
api_key:
12-
description: >
13-
WTI project API key. Overrides the value in the .wti config file.
14-
Recommended: store it as a GitHub Actions secret.
15-
If not provided, the key is read from the .wti file.
12+
description: 'WTI project API key. If not provided, the key is read from the .wti config file.'
1613
required: false
1714

1815
# Config
@@ -33,7 +30,7 @@ inputs:
3330
push_options:
3431
description: 'Additional flags for wti push (e.g. "--merge --ignore-missing --minor")'
3532
required: false
36-
default: ''
33+
default: '--merge --ignore-missing'
3734

3835
# Download options
3936
download_translations:

‎docs/EXAMPLES.md‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,15 +77,28 @@ jobs:
7777
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
7878
```
7979
80-
## Push with merge + ignore missing (safe update)
80+
## Destructive push (override safe defaults)
8181
82-
Avoid obsoleting keys that are missing from the uploaded file and mark changes as minor.
82+
By default the action pushes with `--merge --ignore-missing` so keys on WTI are never accidentally obsoleted. If you need the old destructive behaviour, clear the default flags:
8383

8484
```yaml
8585
- uses: webtranslateit/github-action@v1
8686
with:
8787
api_key: ${{ secrets.WTI_API_KEY }}
88-
push_options: '--merge --ignore-missing --minor'
88+
push_options: ''
89+
```
90+
91+
## Push target files (translations)
92+
93+
Upload translated files alongside source files. Use with caution — target file uploads can overwrite translations done on WTI.
94+
95+
```yaml
96+
- uses: webtranslateit/github-action@v1
97+
with:
98+
api_key: ${{ secrets.WTI_API_KEY }}
99+
upload_translations: true
100+
env:
101+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
89102
```
90103

91104
## Pull specific locales only

‎entrypoint.sh‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,9 @@ if [ "${INPUT_UPLOAD_SOURCES:-true}" = "true" ]; then
7373
PUSH_ARGS+=("--target")
7474
fi
7575

76-
if [ -n "${INPUT_PUSH_OPTIONS:-}" ]; then
77-
SAFE_OPTS=$(sanitize_options "$INPUT_PUSH_OPTIONS")
76+
PUSH_OPTIONS="${INPUT_PUSH_OPTIONS---merge --ignore-missing}"
77+
if [ -n "$PUSH_OPTIONS" ]; then
78+
SAFE_OPTS=$(sanitize_options "$PUSH_OPTIONS")
7879
# Word-split is intentional here for CLI flags
7980
# shellcheck disable=SC2206
8081
PUSH_ARGS+=($SAFE_OPTS)

0 commit comments

Comments
 (0)