Skip to content

A platform for community discussion. Free, open, simple.

DEV: Add runtime deprecation for `translateModKey` (#42996)

Sérgio Saquetima855de4a7aa6
diff --git a/frontend/discourse/app/lib/utilities.js b/frontend/discourse/app/lib/utilities.js
index b52f648145b..0afac8ce296 100644
--- a/frontend/discourse/app/lib/utilities.js
+++ b/frontend/discourse/app/lib/utilities.js
@@ -537,10 +537,19 @@ export async function inCodeBlock(text, pos) {
/**
* Replaces modifier names in a shortcut string with their platform spelling.
*
- * @deprecated Use `formatShortcut` from `discourse/lib/shortcut-format`, which
- * produces the drawn form and the `aria-keyshortcuts` value from one spelling.
+ * @deprecated To draw a shortcut use `DShortcut` (`discourse/ui-kit/d-shortcut`),
+ * which carries the accessible markup too. For the string alone use
+ * `formatShortcut` from `discourse/lib/shortcut-format`.
*/
export function translateModKey(string, separator = " ") {
+ deprecated(
+ "`translateModKey()` is deprecated. To draw a shortcut use `DShortcut` (`discourse/ui-kit/d-shortcut`), which carries the accessible markup too; for the string alone use `formatShortcut()` from `discourse/lib/shortcut-format`.",
+ {
+ since: "2026.9.0",
+ id: "discourse.translate-mod-key",
+ }
+ );
+
const { isApple } = capabilities;
// Apple device users are used to glyphs for shortcut keys
if (isApple) {
diff --git a/frontend/discourse/tests/unit/lib/utilities-test.js b/frontend/discourse/tests/unit/lib/utilities-test.js
index 88c86caf931..4144fea2e10 100644
--- a/frontend/discourse/tests/unit/lib/utilities-test.js
+++ b/frontend/discourse/tests/unit/lib/utilities-test.js
@@ -3,6 +3,7 @@ import { getOwner } from "@ember/owner";
import { setupTest } from "ember-qunit";
import { module, test } from "qunit";
import sinon from "sinon";
+import { withSilencedDeprecations } from "discourse/lib/deprecated";
import {
arrayToTable,
caretRowCol,
@@ -22,6 +23,7 @@ import {
setDefaultHomepage,
slugify,
toAsciiPrintable,
+ translateModKey,
unicodeSlugify,
} from "discourse/lib/utilities";
import Site from "discourse/models/site";
@@ -31,6 +33,10 @@ import {
mdTableSpecialChars,
} from "discourse/tests/fixtures/md-table";
import { chromeTest } from "discourse/tests/helpers/qunit-helpers";
+import {
+ disableRaiseOnDeprecation,
+ enableRaiseOnDeprecation,
+} from "discourse/tests/helpers/raise-on-deprecation";
module("Unit | Utilities", function (hooks) {
setupTest(hooks);
@@ -690,3 +696,44 @@ Random extras
);
});
});
+
+module("Unit | Utilities | translateModKey", function (hooks) {
+ setupTest(hooks);
+
+ hooks.beforeEach(function () {
+ disableRaiseOnDeprecation();
+ this.warnStub = sinon.stub(console, "warn");
+ });
+
+ hooks.afterEach(function () {
+ this.warnStub.restore();
+ enableRaiseOnDeprecation();
+ });
+
+ test("warns that it is deprecated", function (assert) {
+ translateModKey("Shift+Ctrl+A");
+
+ assert.strictEqual(this.warnStub.callCount, 1, "warns once per call");
+ const warning = this.warnStub.firstCall.args[0];
+ assert.true(
+ warning.includes("DShortcut"),
+ "points at the component that draws a shortcut"
+ );
+ assert.true(
+ warning.includes("formatShortcut"),
+ "and at the helper, for a caller that only wants the string"
+ );
+ });
+
+ test("still translates while deprecated", function (assert) {
+ const translated = withSilencedDeprecations(
+ "discourse.translate-mod-key",
+ () => translateModKey("Shift+Alt+A")
+ );
+
+ assert.true(
+ translated.includes("⇧"),
+ "keeps replacing modifier names with their platform spelling"
+ );
+ });
+});