Skip to content

docs: document gambit keyword localization and canonicalKey() pattern - #524

Open
imorland wants to merge 2 commits into
mainfrom
im/gambit-localization-docs
Open

imorland wants to merge 2 commits into
mainfrom
im/gambit-localization-docs

Conversation

@imorland

@imorland imorland commented Apr 14, 2026 •

Copy link
Copy Markdown
Member

Fixes #0000 (no issue: documents flarum/framework#4570, which fixes flarum/framework#4566)

Changes proposed in this pull request:
Documents the English fallback for gambit keywords that flarum/framework#4570 adds in Flarum 2.1. search.md gets a "Localizing gambit keywords" section on canonicalKey(), mapping matched keywords to stable filter values, and translating keywords; language-packs.md points language pack maintainers to it; and the 2.1 section of the 2.x upgrade guide tells extension authors to override canonicalKey() when their key() is translated.

Reviewers should focus on:

Screenshot
N/A

Necessity

  • Has the problem that is being solved here been clearly explained?
  • If applicable, have various options for solving this problem been considered? (N/A, docs.)
  • For core PRs, does this need to be in core, or could it be in an extension? (N/A, docs.)
  • Are we willing to maintain this for years / potentially forever?

Confirmed

  • Frontend changes: tested on a local Flarum installation. (No code changes.)
  • Frontend changes: tests are green (run yarn test in js/). (No code changes.)
  • Frontend changes: tests have been added, or are not appropriate here. (No code changes.)
  • Backend changes: tests are green (run composer test). (No code changes.)
  • Backend changes: tests have been added, or are not appropriate here. (No code changes.)
  • Where applicable, changes are suitable for all supported database drivers (MySQL, MariaDB, PostgreSQL, SQLite). (N/A)
  • Core developer confirmed locally this works as intended.
  • The description above is written by me and describes what this pull request actually does.

Adds a dedicated 'Localizing gambit keywords' section to search.md covering
how key() drives localized search tokens, the canonicalKey() English fallback,
examples for both KeyValueGambit and BooleanGambit, toFilter() canonical value
mapping, and a subsection for language pack maintainers.

Adds a brief note in update-2_0.md flagging canonicalKey() as a required change
for translated gambits. Adds a pointer in language-packs.md explaining gambit
keyword translation keys.
@imorland
imorland force-pushed the im/gambit-localization-docs branch from 3a469cf to 53e58b9 Compare October 19, 2026 18:31
@imorland imorland added this to the 2.1 milestone Oct 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[2.x] Hardcoded gambit keywords prevent localization

1 participant