Skip to content

Templates: Introduced an optional add-on with GitHub's wording in Forgejo's languages - #185

Merged
whereareiam merged 1 commit into
devfrom
feat/theme-phrases
Nov 14, 2026
Merged

whereareiam merged 1 commit into
devfrom
feat/theme-phrases

Conversation

@whereareiam

@whereareiam whereareiam commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Summary

The theme can now show GitHub's wording where Forgejo has no translation of its own, as an optional add-on, without touching Forgejo's translations. By default nothing changes: the templates keep Forgejo's wording.

  • Why not Forgejo's locale files: Forgejo reads a custom locale file instead of its own, never on top of it (options.Locale returns the first layer that has the file). Adding keys that way would replace all of Forgejo's translations for that language, and any an admin customised.

  • How it works: the theme's phrases live in locales/<lang>.json, one file per language, as a string or one string per plural form. The build compiles them with Forgejo's plural rule for each language into the template theme/phrase (scripts/phrases.ts). A template asks for a phrase with Forgejo's own text as the fallback:

    {{template "theme/phrase" dict "Key" "pulls.checks.group_failing" "Count" 2 "Fallback" (ctx.Locale.Tr "repo.pulls.status_checks_failure")}}
    
  • Optional for admins: theme-github-templates.tar.gz ships a theme/phrase that prints only the fallback, so the templates show Forgejo's translations. The new theme-github-wording.tar.gz holds just the compiled theme/phrase; extracting it into <forgejo-data> after the templates switches to GitHub's wording. Since it replaces a file of the templates, it is extracted again after each templates update (README step 3).

  • No English in other languages: with the add-on, a reader whose language has no theme phrases (one an admin adds beyond Forgejo's defaults) still sees Forgejo's text.

  • Languages: all 31 Forgejo enables by default. The wording follows each language's existing Forgejo terms (for example Prüfung, проверка, 合并请求). The translations are mine, not GitHub's, so native speakers may want to refine them later.

  • Local preview: applies the add-on, so the preview can be compared with GitHub; FORGEJO_PREVIEW_GITHUB_WORDING=false bun dev:forgejo:sync shows the templates without it.

  • Checks: a test fails when a language misses a key, a plural form its rule needs, or a placeholder the English phrase uses, checks the plural rules against Forgejo's, and that the templates pack keeps Forgejo's wording.

The first phrases are the merge box's, used by #184. This PR alone changes nothing visible.

Before and after

#184's merge box, with the templates alone and with the wording add-on, at 1280px in the dark theme.

Templates only (default) With theme-github-wording.tar.gz
Merge box with Forgejo's wording Merge box with GitHub's wording

Release notes

  • The title follows Area: Description with a listed area
  • The title describes the effect in the past tense, for example Branches: Fixed ...
  • Exactly one label: feature, change, bug, dependencies, or skip-changelog
  • bug only for a bug that shipped in a release; a fix for a bug that only existed on dev is skip-changelog
  • major added when admins must act on upgrade, for example a new minimum Forgejo version
  • Upgrade steps or warnings added to .github/release-notes.md, if admins need them

Checks

bun check, bun vitest (709 tests) and prettier pass. The release packaging builds both archives (theme-github-wording.tar.gz holds only templates/theme/phrase.tmpl). README and ARCHITECTURE.md describe the add-on.

🤖 Generated with Claude Code

Forgejo reads a custom locale file instead of its own, never on top of it,
so the theme could not add GitHub's wording without replacing Forgejo's
translations and any an admin customised. The theme now keeps its own
phrases in locales/<lang>.json for every language Forgejo enables by
default, and the build compiles them with Forgejo's plural rules into the
template theme/phrase. A template asks for a phrase with Forgejo's text as
the fallback.

The wording is optional. The templates pack's theme/phrase prints only
Forgejo's text, so the pack keeps Forgejo's translations. The compiled
template ships alone in theme-github-wording.tar.gz, which admins extract
over the pack for GitHub's wording; a reader in a language without theme
phrases still sees Forgejo's. The local preview applies it unless
FORGEJO_PREVIEW_GITHUB_WORDING=false.

The first phrases are the merge box's: check titles, counts and groups,
the clean, conflict and draft rows, and the merged and closed boxes. A
test keeps every language complete, with its plural forms and the English
placeholders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@whereareiam whereareiam changed the title Templates: Introduced the theme's own translated phrases for GitHub's wording Templates: Introduced an optional add-on with GitHub's wording in Forgejo's languages Nov 14, 2026
@whereareiam
whereareiam merged commit 4884eaa into dev Nov 14, 2026
6 checks passed
@whereareiam
whereareiam deleted the feat/theme-phrases branch November 14, 2026 15:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature Something new for users

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant