feat: allow translated field labels, add docs

packages/blockly/core/field.ts

@@ -254,7 +254,7 @@ export abstract class Field<T = any>
       this.setTooltip(parsing.replaceMessageReferences(config.tooltip));
     }
     if (config.ariaTypeName) {
-      this.ariaTypeName = config.ariaTypeName;
+      this.setAriaTypeName(config.ariaTypeName);
     }
   }
 
@@ -322,12 +322,15 @@ export abstract class Field<T = any>
    * Sets the ARIA-friendly label representation of this field's type.
    *
    * Implementations are responsible for, and encouraged to, set a localized
-   * version of the ARIA representation of the field's type.
+   * version of the ARIA representation of the field's type. To that end, the
+   * provided value may contain message references of the form `%{BKY_...}`
+   * (e.g. `%{BKY_MY_FIELD_ARIA_TYPE}`), which are replaced with the
+   * corresponding `Blockly.Msg` value.
    *
    * @param ariaTypeName An ARIA representation of the field's type.
    */
   setAriaTypeName(ariaTypeName: string) {
-    this.ariaTypeName = ariaTypeName;
+    this.ariaTypeName = parsing.replaceMessageReferences(ariaTypeName);
   }
 
   /**

packages/blockly/core/interfaces/i_json_block_definition.ts

@@ -71,28 +71,39 @@ interface UnknownArg {
   [key: string]: unknown;
 }
 
+/**
+ * A custom ARIA label for the input, used in place of the label derived from
+ * the input's preceding fields. May contain message references of the form
+ * `%{BKY_...}`, which are replaced with the corresponding `Blockly.Msg` value.
+ */
+type AriaLabelText = string;
+
 /** Input args */
 interface InputValueArg {
   type: 'input_value';
   name?: string;
   check?: string | string[];
   align?: Align;
+  ariaLabelText?: AriaLabelText;
 }
 
 interface InputStatementArg {
   type: 'input_statement';
   name?: string;
   check?: string | string[];
+  ariaLabelText?: AriaLabelText;
 }
 
 interface InputDummyArg {
   type: 'input_dummy';
   name?: string;
+  ariaLabelText?: AriaLabelText;
 }
 
 interface InputEndRowArg {
   type: 'input_end_row';
   name?: string;
+  ariaLabelText?: AriaLabelText;
 }
 
 /** Field args */

packages/blockly/tests/mocha/block_json_test.js

@@ -805,5 +805,95 @@ suite('Block JSON initialization', function () {
       delete Blockly.Blocks['test_block'];
       delete Blockly.Msg['CUSTOM_ROLE_DESCRIPTION'];
     });
+    test('Custom input aria label', function () {
+      const testBlockDefinition = {
+        'type': 'test_block',
+        'message0': 'test %1',
+        'args0': [
+          {
+            'type': 'input_value',
+            'name': 'INPUT',
+            'ariaLabelText': 'Custom input label',
+          },
+        ],
+      };
+      Blockly.common.defineBlocksWithJsonArray([testBlockDefinition]);
+      const block = this.workspace.newBlock('test_block');
+      assert.equal(
+        block.getInput('INPUT').getAriaLabelText(),
+        'Custom input label',
+        'Expected getAriaLabelText to return the custom label.',
+      );
+      delete Blockly.Blocks['test_block'];
+    });
+    test('Custom input aria label with message reference', function () {
+      const testBlockDefinition = {
+        'type': 'test_block',
+        'message0': 'test %1',
+        'args0': [
+          {
+            'type': 'input_value',
+            'name': 'INPUT',
+            'ariaLabelText': '%{BKY_CUSTOM_INPUT_LABEL}',
+          },
+        ],
+      };
+      Blockly.Msg['CUSTOM_INPUT_LABEL'] = 'Custom input label';
+      Blockly.common.defineBlocksWithJsonArray([testBlockDefinition]);
+      const block = this.workspace.newBlock('test_block');
+      assert.equal(
+        block.getInput('INPUT').getAriaLabelText(),
+        'Custom input label',
+        'Expected getAriaLabelText to return the custom label.',
+      );
+      delete Blockly.Blocks['test_block'];
+      delete Blockly.Msg['CUSTOM_INPUT_LABEL'];
+    });
+    test('Custom field aria type name', function () {
+      const testBlockDefinition = {
+        'type': 'test_block',
+        'message0': 'test %1',
+        'args0': [
+          {
+            'type': 'field_number',
+            'name': 'FIELD',
+            'value': 100,
+            'ariaTypeName': 'speed',
+          },
+        ],
+      };
+      Blockly.common.defineBlocksWithJsonArray([testBlockDefinition]);
+      const block = this.workspace.newBlock('test_block');
+      assert.equal(
+        block.getField('FIELD').getAriaTypeName(),
+        'speed',
+        'Expected getAriaTypeName to return the custom type name.',
+      );
+      delete Blockly.Blocks['test_block'];
+    });
+    test('Custom field aria type name with message reference', function () {
+      const testBlockDefinition = {
+        'type': 'test_block',
+        'message0': 'test %1',
+        'args0': [
+          {
+            'type': 'field_number',
+            'name': 'FIELD',
+            'value': 100,
+            'ariaTypeName': '%{BKY_CUSTOM_FIELD_TYPE}',
+          },
+        ],
+      };
+      Blockly.Msg['CUSTOM_FIELD_TYPE'] = 'speed';
+      Blockly.common.defineBlocksWithJsonArray([testBlockDefinition]);
+      const block = this.workspace.newBlock('test_block');
+      assert.equal(
+        block.getField('FIELD').getAriaTypeName(),
+        'speed',
+        'Expected getAriaTypeName to return the custom type name.',
+      );
+      delete Blockly.Blocks['test_block'];
+      delete Blockly.Msg['CUSTOM_FIELD_TYPE'];
+    });
   });
 });

packages/blockly/tests/mocha/field_test.js

@@ -851,6 +851,26 @@ suite('Abstract Fields', function () {
         const field = CustomField.fromJson({ariaTypeName: 'text input'});
         assert.equal(field.getAriaTypeName(), 'text input');
       });
+
+      suite('W/ Msg References', function () {
+        setup(function () {
+          addMessageToCleanup(this.sharedCleanup, 'ARIA_TYPE');
+          Blockly.Msg['ARIA_TYPE'] = 'speed';
+        });
+
+        test('setAriaTypeName resolves message references', function () {
+          const field = new TestField();
+          field.setAriaTypeName('%{BKY_ARIA_TYPE}');
+          assert.equal(field.getAriaTypeName(), 'speed');
+        });
+
+        test('Configured ariaTypeName resolves message references', function () {
+          const field = new TestField('value', {
+            ariaTypeName: '%{BKY_ARIA_TYPE}',
+          });
+          assert.equal(field.getAriaTypeName(), 'speed');
+        });
+      });
     });
 
     suite('getAriaValue', function () {