TurboWarp · PPPDUD · Oct 16, 2025 · Oct 16, 2025 · Oct 16, 2025 · Oct 16, 2025
diff --git a/docs/development/extensions/assorted-apis.md b/docs/development/extensions/assorted-apis.md
@@ -92,6 +92,13 @@ While the block's shape will look similar to "stop this script" and "stop all",
 
 <ExtensionCode title="terminal">{require("!raw-loader!@site/static/example-extensions/terminal.js")}</ExtensionCode>
 
+## Translations
+Use the `Scratch.translate()` API to translate text for use in block text and extension names. This is NOT the same as the Translate extension from Scratch; `Scratch.translate()` does not use the Internet and exclusively uses man-made translations.
+
+`Scratch.translate()` is not intended for translating user input and will leave most user-generated text untranslated.
+
+If you want to help translate text from your extension, [click here](https://docs.turbowarp.org/translate).
+
 ## Next steps
 
 Next, let's see [how to make blocks like "when I receive" or "when timer greater than".](./hats)
diff --git a/docs/development/extensions/compatibility.md b/docs/development/extensions/compatibility.md
@@ -105,7 +105,7 @@ Instead, create a new block and mark the old one as `hideFromPalette: true`. The
         {
           blockType: Scratch.BlockType.REPORTER,
           id: "oldBlock",
-          text: "old [INPUT1]",
+          text: Scratch.translate("old [INPUT1]"),
           arguments: {
             INPUT1: { /* ... */ }
           },
@@ -114,7 +114,7 @@ Instead, create a new block and mark the old one as `hideFromPalette: true`. The
         {
           blockType: Scratch.BlockType.REPORTER,
           opcode: "newBlock",
-          text: "new [INPUT1] [INPUT2]",
+          text: Scratch.translate("new [INPUT1] [INPUT2]"),
           arguments: {
             INPUT1: { /* ... */ },
             INPUT2: { /* ... */ }

diff --git a/docs/development/extensions/hello-world.md b/docs/development/extensions/hello-world.md
@@ -46,12 +46,12 @@ Make sure to always call register() exactly once. If you don't call it, your ext
   getInfo() {
     return {
       id: 'helloworld',
-      name: 'It works!',
+      name: Scratch.translate('It works!'),
       blocks: [
         {
           opcode: 'hello',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'Hello, world!'
+          text: Scratch.translate('Hello, world!')
         }
       ]
     };

diff --git a/static/example-extensions/async.js b/static/example-extensions/async.js
@@ -2,11 +2,11 @@ class AsyncExtension {
   getInfo() {
     return {
       id: 'asyncexample',
-      name: 'Async Blocks',
+      name: Scratch.translate('Async Blocks'),
       blocks: [
         {
           opcode: 'wait',
-          text: 'wait [TIME] seconds',
+          text: Scratch.translate('wait [TIME] seconds'),
           blockType: Scratch.BlockType.COMMAND,
           arguments: {
             TIME: {
@@ -17,7 +17,7 @@ class AsyncExtension {
         },
         {
           opcode: 'fetch',
-          text: 'fetch [URL]',
+          text: Scratch.translate('fetch [URL]'),
           blockType: Scratch.BlockType.REPORTER,
           arguments: {
             URL: {
@@ -54,4 +54,4 @@ class AsyncExtension {
   }
   // highlight-end
 }
-Scratch.extensions.register(new AsyncExtension());
+Scratch.extensions.register(new AsyncExtension());
diff --git a/static/example-extensions/cast.js b/static/example-extensions/cast.js
@@ -2,12 +2,12 @@ class CastingExample {
   getInfo() {
     return {
       id: 'castexample',
-      name: 'Casting Example',
+      name: Scratch.translate('Casting Example'),
       blocks: [
         {
           opcode: 'toNumber',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'convert [INPUT] to number',
+          text: Scratch.translate('convert [INPUT] to number'),
           arguments: {
             INPUT: {
               type: Scratch.ArgumentType.STRING,
@@ -20,7 +20,7 @@ class CastingExample {
           // treatment in JS, it seems a bit dangerous to use
           opcode: 'castToString',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'convert [INPUT] to string',
+          text: Scratch.translate('convert [INPUT] to string'),
           arguments: {
             INPUT: {
               type: Scratch.ArgumentType.STRING,
@@ -31,7 +31,7 @@ class CastingExample {
         {
           opcode: 'toBoolean',
           blockType: Scratch.BlockType.BOOLEAN,
-          text: 'convert [INPUT] to boolean',
+          text: Scratch.translate('convert [INPUT] to boolean'),
           arguments: {
             INPUT: {
               type: Scratch.ArgumentType.STRING,
@@ -42,7 +42,7 @@ class CastingExample {
         {
           opcode: 'compare',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'compare [A] to [B]',
+          text: Scratch.translate('compare [A] to [B]'),
           arguments: {
             A: {
               type: Scratch.ArgumentType.STRING,

diff --git a/static/example-extensions/color.js b/static/example-extensions/color.js
@@ -13,7 +13,7 @@ class ColorExample {
         {
           opcode: 'reporter',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'string [STRING] boolean [BOOLEAN] menu [MENU] field [FIELD]',
+          text: Scratch.translate('string [STRING] boolean [BOOLEAN] menu [MENU] field [FIELD]'),
           arguments: {
             STRING: {
               type: Scratch.ArgumentType.STRING,

diff --git a/static/example-extensions/filter.js b/static/example-extensions/filter.js
@@ -2,31 +2,31 @@ class FilterExample {
   getInfo() {
     return {
       id: 'filterexample',
-      name: 'Filter Example',
+      name: Scratch.translate('Filter Example'),
       blocks: [
         {
           opcode: 'all',
           blockType: Scratch.BlockType.COMMAND,
-          text: 'available in ALL targets',
+          text: Scratch.translate('available in ALL targets'),
         },
         {
           opcode: 'sprites',
           blockType: Scratch.BlockType.COMMAND,
-          text: 'available in ONLY sprites',
+          text: Scratch.translate('available in ONLY sprites'),
           // highlight-next-line
           filter: [Scratch.TargetType.SPRITE]
         },
         {
           opcode: 'stage',
           blockType: Scratch.BlockType.COMMAND,
-          text: 'available in ONLY the stage',
+          text: Scratch.translate('available in ONLY the stage'),
           // highlight-next-line
           filter: [Scratch.TargetType.STAGE]
         },
         {
           opcode: 'none',
           blockType: Scratch.BlockType.COMMAND,
-          text: 'available in NEITHER sprites or the stage',
+          text: Scratch.translate('available in NEITHER sprites or the stage'),
           // highlight-start
           // NOTE: Use hideFromPalette instead of filter: []
           filter: []

diff --git a/static/example-extensions/hello-docs.js b/static/example-extensions/hello-docs.js
@@ -2,14 +2,14 @@ class HelloDocs {
   getInfo() {
     return {
       id: 'hellodocs',
-      name: 'Hello Docs!',
+      name: Scratch.translate('Hello Docs!'),
       // highlight-next-line
       docsURI: 'https://docs.turbowarp.org/development/extensions/docsURI-demo',
       blocks: [
         {
           opcode: 'hello',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'Hello!'
+          text: Scratch.translate('Hello!')
         }
       ]
     };

diff --git a/static/example-extensions/hello-world.js b/static/example-extensions/hello-world.js
@@ -2,12 +2,12 @@ class HelloWorld {
   getInfo() {
     return {
       id: 'helloworld',
-      name: 'It works!',
+      name: Scratch.translate('It works!'),
       blocks: [
         {
           opcode: 'hello',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'Hello!'
+          text: Scratch.translate('Hello!')
         }
       ]
     };

diff --git a/static/example-extensions/hidden-1.js b/static/example-extensions/hidden-1.js
@@ -2,12 +2,12 @@ class HideFromPaletteExample {
   getInfo() {
     return {
       id: 'hidefrompaletteexample',
-      name: 'hideFromPalette Example',
+      name: Scratch.translate('hideFromPalette Example'),
       blocks: [
         {
           opcode: 'hidden',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'example block (visible)'
+          text: Scratch.translate('example block (visible)')
         },
       ]
     };

diff --git a/static/example-extensions/hidden-2.js b/static/example-extensions/hidden-2.js
@@ -2,12 +2,12 @@ class HideFromPaletteExample {
   getInfo() {
     return {
       id: 'hidefrompaletteexample',
-      name: 'hideFromPalette Example',
+      name: Scratch.translate('hideFromPalette Example'),
       blocks: [
         {
           opcode: 'hidden',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'example block (hidden)',
+          text: Scratch.translate('example block (hidden)'),
           hideFromPalette: true
         },
       ]

diff --git a/static/example-extensions/icons.js b/static/example-extensions/icons.js
@@ -11,7 +11,7 @@ class IconsExample {
   getInfo() {
     return {
       id: 'iconsexample',
-      name: 'Icons Example',
+      name: Scratch.translate('Icons Example'),
       // highlight-start
       menuIconURI: blocksIcon,
       blockIconURI: dangoIcon,
@@ -20,7 +20,7 @@ class IconsExample {
         {
           opcode: 'defaultIcon',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'reporter with default icon [INPUT]',
+          text: Scratch.translate('reporter with default icon [INPUT]'),
           arguments: {
             INPUT: {
               type: Scratch.ArgumentType.STRING,
@@ -31,7 +31,7 @@ class IconsExample {
         {
           opcode: 'overriddenIcon',
           blockType: Scratch.BlockType.COMMAND,
-          text: 'command with overridden icon [INPUT]',
+          text: Scratch.translate('command with overridden icon [INPUT]'),
           // highlight-next-line
           blockIconURI: colorIcon,
           arguments: {

diff --git a/static/example-extensions/inline-images.js b/static/example-extensions/inline-images.js
@@ -8,13 +8,13 @@ class InlineImagesExample {
   getInfo() {
     return {
       id: 'inlineimagesexample',
-      name: 'Inline Images Example',
+      name: Scratch.translate('Inline Images Example'),
       blocks: [
         {
           opcode: 'reporter',
           blockType: Scratch.BlockType.REPORTER,
           // highlight-start
-          text: 'some text [IMAGE] more text',
+          text: Scratch.translate('some text [IMAGE] more text'),
           arguments: {
             IMAGE: {
               type: Scratch.ArgumentType.IMAGE,
@@ -28,7 +28,7 @@ class InlineImagesExample {
           blockType: Scratch.BlockType.COMMAND,
           blockIconURI: colorIcon,
           // highlight-start
-          text: 'some text [IMAGE] more text',
+          text: Scratch.translate('some text [IMAGE] more text'),
           arguments: {
             IMAGE: {
               type: Scratch.ArgumentType.IMAGE,

diff --git a/static/example-extensions/separators.js b/static/example-extensions/separators.js
@@ -2,31 +2,31 @@ class SeparatorExample {
   getInfo() {
     return {
       id: 'separatorexample',
-      name: 'Separator Example',
+      name: Scratch.translate('Separator Example'),
       blocks: [
         {
           opcode: 'block1',
           blockType: Scratch.BlockType.COMMAND,
-          text: 'group 1'
+          text: Scratch.translate('group 1')
         },
         {
           opcode: 'block2',
           blockType: Scratch.BlockType.COMMAND,
-          text: 'also group 1',
+          text: Scratch.translate('also group 1'),
         },
         // highlight-next-line
         '---',
         {
           opcode: 'block3',
           blockType: Scratch.BlockType.COMMAND,
-          text: 'group 2'
+          text: Scratch.translate('group 2')
         },
         // highlight-next-line
         '---',
         {
           opcode: 'block4',
           blockType: Scratch.BlockType.COMMAND,
-          text: 'group 3',
+          text: Scratch.translate('group 3'),
         },
       ]
     };

diff --git a/static/example-extensions/strict-equality.js b/static/example-extensions/strict-equality.js
@@ -2,13 +2,13 @@ class StrictEqualityExtension {
   getInfo() {
     return {
       id: 'strictequalityexample',
-      name: 'Strict Equality',
+      name: Scratch.translate('Strict Equality'),
       blocks: [
         // highlight-start
         {
           opcode: 'strictlyEquals',
           blockType: Scratch.BlockType.BOOLEAN,
-          text: '[ONE] strictly equals [TWO]',
+          text: Scratch.translate('[ONE] strictly equals [TWO]'),
           arguments: {
             ONE: {
               type: Scratch.ArgumentType.STRING

diff --git a/static/example-extensions/strings-1.js b/static/example-extensions/strings-1.js
@@ -2,12 +2,12 @@ class Strings1 {
   getInfo() {
     return {
       id: 'strings1example',
-      name: 'Encoding',
+      name: Scratch.translate('Encoding'),
       blocks: [
         {
           opcode: 'convert',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'convert [TEXT] to [FORMAT]',
+          text: Scratch.translate('convert [TEXT] to [FORMAT]'),
           arguments: {
             TEXT: {
               type: Scratch.ArgumentType.STRING,

diff --git a/static/example-extensions/strings-2.js b/static/example-extensions/strings-2.js
@@ -2,12 +2,12 @@ class Strings2 {
   getInfo() {
     return {
       id: 'strings2example',
-      name: 'Encoding',
+      name: Scratch.translate('Encoding'),
       blocks: [
         {
           opcode: 'convert',
           blockType: Scratch.BlockType.REPORTER,
-          text: 'convert [TEXT] to [FORMAT]',
+          text: Scratch.translate('convert [TEXT] to [FORMAT]'),
           arguments: {
             TEXT: {
               type: Scratch.ArgumentType.STRING,

diff --git a/static/example-extensions/terminal.js b/static/example-extensions/terminal.js
@@ -2,14 +2,14 @@ class TerminalExample {
   getInfo() {
     return {
       id: 'terminalexample',
-      name: 'Terminal Example',
+      name: Scratch.translate('Terminal Example'),
       blocks: [
         {
           opcode: 'terminalBlock',
           blockType: Scratch.BlockType.COMMAND,
           // highlight-next-line
           isTerminal: true,
-          text: 'you can not connect another block under this one!'
+          text: Scratch.translate('you can not connect another block under this one!')
         }
       ]
     };