Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
230 changes: 230 additions & 0 deletions .github/workflows/i18n-sync.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,230 @@
name: Sync translations

# Keeps the 49 translations in step with src/i18n/en.json without ever
# blocking English, the way Omarchy's and folio's i18n-sync workflows do. One
# credential-less Muse runner per pending language translates; a
# credential-less collect job takes only each language's own catalog,
# validates the result with the catalog tests, and hands it on as a patch;
# a trusted land job, which runs no repository code, path-checks that patch
# and lands it as one pull request it merges itself.
#
# Repository settings this needs: the MUSE_API_KEY Actions secret (and an
# optional MUSE_MODEL variable), and an I18N_SYNC_TOKEN secret (a
# fine-grained PAT with contents + pull-requests write on this repo) for
# the bot that opens and merges the pull request.
on:
push:
branches: [master]
paths:
- 'src/i18n/en.json'
workflow_dispatch:
schedule:
# Retry unfinished translations.
- cron: '17 4 * * *'

permissions:
contents: read

concurrency:
group: i18n-sync
cancel-in-progress: false

jobs:
prepare:
runs-on: ubuntu-latest
timeout-minutes: 5
outputs:
locales: ${{ steps.pending.outputs.locales }}
sha: ${{ steps.pending.outputs.sha }}
steps:
- uses: actions/checkout@v4
with:
ref: master
persist-credentials: false
- name: Find pending translations
id: pending
run: |
echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
echo "locales=$(python3 scripts/i18n-sync.py pending | jq -c .locales)" >> "$GITHUB_OUTPUT"

translate:
needs: prepare
if: needs.prepare.outputs.locales != '[]'
strategy:
fail-fast: false
matrix:
locale: ${{ fromJSON(needs.prepare.outputs.locales) }}
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@v4
with:
ref: ${{ needs.prepare.outputs.sha }}
persist-credentials: false
- name: Install Muse
# Keep the pin in step with omacom/omarchy's i18n-sync workflow.
run: |
mkdir -p "$RUNNER_TEMP/muse-bin"
curl --fail --silent --show-error --location https://api.meta.ai/muse-launcher.sh --output "$RUNNER_TEMP/muse-bin/muse"
echo "c6db294799a190ca380da274beb3b9c0e160e0da9681a3d364ce8b0e5fa3a4bc $RUNNER_TEMP/muse-bin/muse" | sha256sum --check
chmod +x "$RUNNER_TEMP/muse-bin/muse"
MUSE_LAUNCHER_INSTALL=1 "$RUNNER_TEMP/muse-bin/muse"
echo "MUSE_NO_AUTO_UPDATE=1" >> "$GITHUB_ENV"
echo "$RUNNER_TEMP/muse-bin" >> "$GITHUB_PATH"
- name: Configure Muse
env:
MUSE_API_KEY: ${{ secrets.MUSE_API_KEY }}
run: |
python3 - <<'PY'
import json, os
from pathlib import Path
key = os.environ.get('MUSE_API_KEY')
if not key:
raise SystemExit('Add the MUSE_API_KEY Actions secret to enable automatic translations.')
config = Path.home() / '.config/muse'
config.mkdir(parents=True, exist_ok=True)
auth = config / 'auth.json'
auth.write_text(json.dumps({'schema_version': 1, 'providers': {'meta': {'api_key': key}}}))
auth.chmod(0o600)
PY
- name: Translate this language's pending strings
# What fails stays pending for the next run; what worked still lands.
continue-on-error: true
timeout-minutes: 35
env:
MUSE_MODEL: ${{ vars.MUSE_MODEL || 'muse-spark-1.3-contributor' }}
LOCALE: ${{ matrix.locale }}
run: python3 scripts/i18n-sync.py translate --locale "$LOCALE" --model "$MUSE_MODEL"
- name: Remove Muse credentials
if: always()
run: rm -f "$HOME/.config/muse/auth.json"
- name: Stage this language's catalog
# A lone file would lose its folders in the artifact; collect looks
# for it under src/i18n.
if: always()
env:
LOCALE: ${{ matrix.locale }}
run: |
mkdir -p "$RUNNER_TEMP/out/src/i18n"
cp "src/i18n/$LOCALE.json" "$RUNNER_TEMP/out/src/i18n/"
- uses: actions/upload-artifact@v4
if: always()
with:
name: translations-${{ matrix.locale }}
path: ${{ runner.temp }}/out
retention-days: 3
if-no-files-found: error

# Takes each runner's own catalog and nothing else, and validates the
# whole set with the catalog tests, with no credentials. The outcome
# leaves as a patch for land.
collect:
needs: [prepare, translate]
# Keep the languages that finished even when another runner failed.
if: ${{ always() && !cancelled() && needs.prepare.result == 'success' && needs.prepare.outputs.locales != '[]' }}
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
with:
ref: ${{ needs.prepare.outputs.sha }}
persist-credentials: false
- uses: actions/download-artifact@v4
with:
pattern: translations-*
path: ${{ runner.temp }}/translations
- name: Collect completed translations
env:
EXPECTED: ${{ needs.prepare.outputs.locales }}
run: python3 scripts/i18n-sync.py collect "$RUNNER_TEMP/translations" --expected "$(jq -r 'join(",")' <<< "$EXPECTED")"
- name: Validate with the catalog tests
# Built against Arch's Qt, like Hype's own CI. The packages are
# listed here rather than read from omarchy-pkgs' PKGBUILD, so no
# code from outside this repository runs beside what land trusts.
run: |
docker run --rm -v "$PWD:/hype" -w /hype archlinux:latest bash -euc '
pacman -Syu --noconfirm --needed base-devel cmake libwebp zlib \
qt6-base qt6-declarative qt6-multimedia qt6-svg qt6-webengine >/dev/null
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release >/dev/null
cmake --build build --target hype_tests -j"$(nproc)"
QT_QPA_PLATFORM=offscreen build/hype_tests catalogsMatchTheEnglishOne everyCatalogIsCompiledIn
'
- name: Package the collected translations
run: |
mkdir -p "$RUNNER_TEMP/collected"
git diff --binary --no-renames -- src/i18n > "$RUNNER_TEMP/collected/translations.patch"
- uses: actions/upload-artifact@v4
with:
name: collected
path: ${{ runner.temp }}/collected/translations.patch
retention-days: 3
if-no-files-found: error
- name: Report what's still pending
if: always()
run: |
python3 scripts/i18n-sync.py pending | jq -r '"Strings still pending: **\([.jobs[].pending | length] | add // 0)** across \(.locales | length) languages. English shows meanwhile; the next run retries them."' >> "$GITHUB_STEP_SUMMARY"

# Lands the collected translations as one pull request. This job holds the
# write token, so it runs no repository code: only git, gh, and the path
# check written inline here.
land:
needs: [prepare, collect]
if: ${{ always() && !cancelled() && needs.collect.result == 'success' }}
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
ref: ${{ needs.prepare.outputs.sha }}
token: ${{ secrets.I18N_SYNC_TOKEN || github.token }}
- uses: actions/download-artifact@v4
with:
name: collected
path: ${{ runner.temp }}/collected
- name: Commit, open and merge the pull request
env:
GH_TOKEN: ${{ secrets.I18N_SYNC_TOKEN || github.token }}
run: |
patch="$RUNNER_TEMP/collected/translations.patch"
if [ ! -s "$patch" ]; then
echo "No translations to land."
exit 0
fi
# Only edits to catalogs already here, never en.json, judged from what
# the patch staged: its headers can name one file and change another.
git apply --index "$patch"
# Read as plain commands, so a git failure stops the step rather than reading as empty.
summary=$(git diff --cached --summary)
git diff --cached --name-status --no-renames -z > "$RUNNER_TEMP/staged"
if [ -n "$summary" ]; then
echo "collected translations do more than change catalogs:" >&2
echo "$summary" >&2
exit 1
fi
while IFS= read -r -d '' status && IFS= read -r -d '' path; do
if [[ "$status" != M ]] || ! [[ "$path" =~ ^src/i18n/[a-zA-Z-]+\.json$ ]] || [[ "$path" == */en.json ]] \
|| [[ "$(git ls-tree HEAD -- "$path" | cut -c1-6)" != 100644 ]]; then
echo "collected translations contain a disallowed change: $status $path" >&2
exit 1
fi
done < "$RUNNER_TEMP/staged"
git config user.name 'github-actions[bot]'
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
git commit -m 'Update translations'
git push --force origin HEAD:refs/heads/i18n-sync
# Only this repository's own sync branch: owner:branch matches
# exactly that head, where gh pr list --head also matches forks.
pr=$(gh api "repos/$GITHUB_REPOSITORY/pulls?head=$GITHUB_REPOSITORY_OWNER:i18n-sync&base=master&state=open" --jq '.[0].number // empty')
if [ -z "$pr" ]; then
pr=$(basename "$(gh pr create --base master --head i18n-sync --title 'Update translations' \
--body 'Automated translation sync: fills pending strings in the 49 language catalogs from src/i18n/en.json. Generated by the Sync translations workflow, which validated these catalogs with the catalog tests and merges this pull request itself.')")
fi
# Merged here rather than left open: the next run rebuilds
# i18n-sync from master, so an open pull request would lose these.
if ! gh pr merge --squash --delete-branch "$pr"; then
echo "Could not merge #$pr; its translations stay pending and are redone by the next run." >&2
exit 1
fi
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ Each slide supports one image or video. Copy the whole presentation folder when

## Choose your look

The palette and font icons in the toolbar choose an installed Omarchy theme and a presentation font. Hover to see the current choices. Theme colors apply to text, code, and slide backgrounds; your images keep their original colors. Code stays monospaced. Hype’s interface follows your current desktop theme independently and updates when you change it.
The palette and font icons in the toolbar choose an installed Omarchy theme and a presentation font. Hover to see the current choices. Theme colors apply to text, code, and slide backgrounds; your images keep their original colors. Code stays monospaced. Hype’s interface follows your current desktop theme independently and updates when you change it. It speaks the language picked under Omarchy's **Setup > Language** too, switching as soon as you pick another; your slides stay as you wrote them.

The header shows the presentation's name with your position in it, such as “Slide 4 of 45”; saving and exporting report their progress on that line. The file icon beside it holds New, Open, Save, Export, and Version history, and is highlighted when you have unsaved changes.

Expand Down Expand Up @@ -256,7 +256,7 @@ The build uses a Qt toolchain from Qt's installer under `build/qt/` when present

For a launcher entry that rebuilds this checkout when opened, run `./bin/install-dev` and choose **Hype (Development)**.

Run `./bin/test` for the regression suite: the C++ tests (`hype_tests`, which read exported PDFs back with Qt Pdf from `qt6-webengine`) and the command-line tests (`hype_commands`, in Python). Arguments go to `ctest`, so `./bin/test -R hype_commands` runs only those. Set `HYPE_GUI_TESTS=0` to skip the C++ window-level tests on a machine without multimedia. After building the tests, the presenter check can also run with two virtual displays:
Run `./bin/test` for the regression suite: the C++ tests (`hype_tests`, which read exported PDFs back with Qt Pdf from `qt6-webengine`) and the command-line tests (`hype_commands`, in Python). Arguments go to `ctest`, so `./bin/test -R hype_commands` runs only those. Set `HYPE_GUI_TESTS=0` to skip the C++ window-level tests on a machine without multimedia. Every string the window shows is translated; [docs/i18n.md](docs/i18n.md) covers adding one and how the translations are kept in sync. After building the tests, the presenter check can also run with two virtual displays:

```sh
QT_QPA_PLATFORMTHEME=generic QT_STYLE_OVERRIDE=Fusion \
Expand Down
31 changes: 31 additions & 0 deletions docs/i18n.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Translations

Hype's window follows the language picked under Omarchy's **Setup > Language**, live: English plus Omarchy's 49 translations. Each language has a catalog, `src/i18n/<code>.json`, a flat JSON object from English source text to its translation, compiled into the binary through `src/resources.qrc`. A counted string, `qsTr("%Ln slides selected", "", count)`, maps to an object of plural forms keyed by CLDR category (`{"one": "%Ln slide selected", "other": "%Ln slides selected"}`), and each language gives exactly the categories its counts reach, by the rules in `Translator::pluralCategory`. A string a catalog doesn't have yet shows in English (a regional catalog such as `pt-BR` falls back to `pt` first).

The window and the export worker it starts are translated, so an export's progress and errors arrive in the window's language. The commands (`hype check`, `hype render`, `hype export`) and the command-line exports never install the translator: their output is read by scripts and agents, and stays in English. Slides are the author's and are never translated or mirrored; `slidesRenderTheSameRightToLeft` checks that a right-to-left desktop draws them exactly as written.

`src/translator.h` and `src/translator.cpp` are the copy every Omarchy app carries, byte for byte, from the omarchy-app skill's templates. Change them there, not here.

## Adding or changing a string

Pull requests only ever touch English: wrap the text in `qsTr()` (QML) or `tr()` (C++), with `%1` placeholders filled by `.arg()` rather than a sentence glued together, and add it to `src/i18n/en.json` as itself, or with its `one` and `other` forms when it's counted. A free function in C++ uses its file's `tr()` helper. QML redoes every `qsTr()` binding on a language switch, but text C++ makes and keeps is not: parse errors are cached by translation generation, and `Deck::retranslate` makes the deck's error, title and slide banners again, so a new cache of translated text needs the same. The `englishCatalogMatchesTheSources` test keeps `en.json` exactly in step with the sources. Leave the other catalogs alone. Since the English is the key, rewording a string makes a new key; its translations become pending, and the old key is dropped by the next sync. The catalog tests check the translations that are there (placeholders, plural forms, language codes, every catalog listed in `resources.qrc`), but never require them to be complete, so English is never blocked.

## Keeping translations in sync

The `Sync translations` workflow (`.github/workflows/i18n-sync.yml`) does the converging, the way Omarchy's, Folio's and Signed's do. It runs on pushes to `master` that change `src/i18n/en.json`, daily, and on demand. `scripts/i18n-sync.py pending` lists, per language, the strings that are missing or whose translation no longer fits, and the keys `en.json` no longer has. Then:

1. One runner per pending language, holding only the Muse key and no repository credentials, runs `translate --locale <code>`. Muse only returns text: the script validates every value and writes that one catalog, dropping keys English no longer has. Whatever fails stays pending.
2. A collect job, with no credentials, takes from each runner only its own `<code>.json`, keeps its current and valid entries, and runs the catalog tests against the result in an Arch container.
3. A land job, holding the `I18N_SYNC_TOKEN`, runs no repository code: it checks that applying the patch staged nothing but edits to catalogs already here (never `en.json`, nothing created, deleted, renamed or given another mode), commits it to the `i18n-sync` branch, and opens and merges an `Update translations` pull request. The next run rebuilds that branch from `master`, so a sync pull request is never left open.

A language that failed, or a run that broke, just leaves strings pending for the next run. The same script works locally: `python3 scripts/i18n-sync.py pending` shows the queue, and `translate --locale da` fills one language with a local Muse.

Repository settings this needs:

- `MUSE_API_KEY`, an Actions secret for the translation runners.
- `I18N_SYNC_TOKEN`, an Actions secret holding a fine-grained PAT with Contents and Pull requests read and write on this repository, for the bot that opens and merges the sync pull request. Without it the workflow falls back to its own token, which can still open and merge the pull request, but GitHub runs no CI on a pull request that token opens.
- Optionally `MUSE_MODEL`, an Actions variable naming the Muse model (default `muse-spark-1.3-contributor`).

## Translator brief

The brief Muse gets lives in `scripts/i18n-sync.py` (`BRIEF`); it applies to people translating by hand too. Keep the name Hype, and translate "slide", "presentation", "overview", "presenter view" and "speaker notes" the way the language's presentation software names them. Write like the interface was made in the language: short, natural, the register of consumer desktop software. Keep exactly: product and brand names, file formats and names, the `images/` and `videos/` folders, the words an author types into a slide (`span`, `fit`, an `svg` block, `--name` theme colors), key names and symbols, units, and placeholders: `%1` to `%9` and `%Ln` must all be there, though they may be reordered. In a plural entry, `other` keeps every placeholder, and another form may drop `%Ln` only where the language says that number with a word. `pt` is European Portuguese and `pt-BR` Brazilian; `sr` is Serbian in Cyrillic.
Loading
Loading