diff --git a/docs/development/extensions/assorted-apis.md b/docs/development/extensions/assorted-apis.md index 3f84d8a6..807fe8d3 100644 --- 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", {require("!raw-loader!@site/static/example-extensions/terminal.js")} +## 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 index 2bde2c90..061d764d 100644 --- 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 index 3009beba..85888b52 100644 --- 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 index 81261835..8b855aa7 100644 --- 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()); \ No newline at end of file +Scratch.extensions.register(new AsyncExtension()); diff --git a/static/example-extensions/cast.js b/static/example-extensions/cast.js index e161a8c6..7faace76 100644 --- 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 index 34e976f8..6e6d8b61 100644 --- 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 index 1ab40326..6b627685 100644 --- 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 index 97e15449..a7cfb2d3 100644 --- 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 index 71778994..98853b08 100644 --- 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 index c395f255..0fbc95a1 100644 --- 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 index b0625d92..130d8e9c 100644 --- 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 index 38798d75..b92a2db2 100644 --- 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 index bb10847f..c56818d6 100644 --- 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 index 5142a38e..fb69dcfe 100644 --- 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 index ce9fe97e..d869f422 100644 --- 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 index 18711f3d..54fc0ee1 100644 --- 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 index 1ec5517b..f0c5bbe4 100644 --- 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 index cdc995a6..40659b53 100644 --- 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!') } ] }; diff --git a/static/example-extensions/timer-reimplementation.js b/static/example-extensions/timer-reimplementation.js index 5756c203..7b9fe01b 100644 --- a/static/example-extensions/timer-reimplementation.js +++ b/static/example-extensions/timer-reimplementation.js @@ -4,13 +4,13 @@ class TimerReimplementationExample { getInfo() { return { id: 'timerreimplementationexample', - name: 'Timer Example', + name: Scratch.translate('Timer Example'), blocks: [ // highlight-start { opcode: 'whenTimerGreaterThan', blockType: Scratch.BlockType.HAT, - text: 'when timer > [TIME]', + text: Scratch.translate('when timer > [TIME]'), isEdgeActivated: true, arguments: { TIME: { @@ -23,12 +23,12 @@ class TimerReimplementationExample { { opcode: 'timer', blockType: Scratch.BlockType.REPORTER, - text: 'timer' + text: Scratch.translate('timer') }, { opcode: 'resetTimer', blockType: Scratch.BlockType.COMMAND, - text: 'reset timer' + text: Scratch.translate('reset timer') } ] }; diff --git a/static/example-extensions/unmonitorable.js b/static/example-extensions/unmonitorable.js index 24df342a..53dec0c2 100644 --- a/static/example-extensions/unmonitorable.js +++ b/static/example-extensions/unmonitorable.js @@ -2,17 +2,17 @@ class DisableMonitorExample { getInfo() { return { id: 'disablemonitorexample', - name: 'disableMonitor Example', + name: Scratch.translate('disableMonitor Example'), blocks: [ { opcode: 'monitorable', blockType: Scratch.BlockType.REPORTER, - text: 'this block can be monitored' + text: Scratch.translate('this block can be monitored') }, { opcode: 'unmonitorable', blockType: Scratch.BlockType.REPORTER, - text: 'but this one can not', + text: Scratch.translate('but this one can not'), // highlight-next-line disableMonitor: true }, diff --git a/static/example-extensions/unsandboxed/block-utility-examples.js b/static/example-extensions/unsandboxed/block-utility-examples.js index 6c14aceb..9c606bf3 100644 --- a/static/example-extensions/unsandboxed/block-utility-examples.js +++ b/static/example-extensions/unsandboxed/block-utility-examples.js @@ -9,16 +9,16 @@ getInfo() { return { id: 'blockutilityexamples', - name: 'BlockUtility Examples', + name: Scratch.translate('BlockUtility Examples'), blocks: [ { opcode: 'getSpriteName', - text: 'sprite name', + text: Scratch.translate('sprite name'), blockType: Scratch.BlockType.REPORTER, }, { opcode: 'doesVariableExist', - text: 'is there a [TYPE] named [NAME]?', + text: Scratch.translate('is there a [TYPE] named [NAME]?'), blockType: Scratch.BlockType.BOOLEAN, arguments: { NAME: { diff --git a/static/example-extensions/unsandboxed/broadcast-5.js b/static/example-extensions/unsandboxed/broadcast-5.js index 0b9df60f..3314ac43 100644 --- a/static/example-extensions/unsandboxed/broadcast-5.js +++ b/static/example-extensions/unsandboxed/broadcast-5.js @@ -4,12 +4,12 @@ getInfo() { return { id: 'broadcast5example', - name: 'Broadcast Example 5', + name: Scratch.translate('Broadcast Example 5'), blocks: [ { opcode: 'whenReceived', blockType: Scratch.BlockType.HAT, - text: 'when I receive [EVENT_OPTION]', + text: Scratch.translate('when I receive [EVENT_OPTION]'), isEdgeActivated: false, arguments: { EVENT_OPTION: { @@ -21,7 +21,7 @@ { opcode: 'broadcast', blockType: Scratch.BlockType.REPORTER, - text: 'broadcast [EVENT]', + text: Scratch.translate('broadcast [EVENT]'), arguments: { EVENT: { type: Scratch.ArgumentType.STRING, diff --git a/static/example-extensions/unsandboxed/hello-world-unsandboxed.js b/static/example-extensions/unsandboxed/hello-world-unsandboxed.js index 3aa70a3f..9ea680ab 100644 --- a/static/example-extensions/unsandboxed/hello-world-unsandboxed.js +++ b/static/example-extensions/unsandboxed/hello-world-unsandboxed.js @@ -9,12 +9,12 @@ getInfo() { return { id: 'helloworldunsandboxed', - name: 'Unsandboxed Hello World', + name: Scratch.translate('Unsandboxed Hello World'), blocks: [ { opcode: 'hello', blockType: Scratch.BlockType.REPORTER, - text: 'Hello!' + text: Scratch.translate('Hello!') } ] }; diff --git a/static/example-extensions/unsandboxed/turbo-mode.js b/static/example-extensions/unsandboxed/turbo-mode.js index b2383e70..7f920e7c 100644 --- a/static/example-extensions/unsandboxed/turbo-mode.js +++ b/static/example-extensions/unsandboxed/turbo-mode.js @@ -12,12 +12,12 @@ getInfo() { return { id: 'turbomodeunsandboxed', - name: 'Turbo Mode', + name: Scratch.translate('Turbo Mode'), blocks: [ { opcode: 'set', blockType: Scratch.BlockType.COMMAND, - text: 'set turbo mode to [ENABLED]', + text: Scratch.translate('set turbo mode to [ENABLED]'), arguments: { ENABLED: { type: Scratch.ArgumentType.STRING, diff --git a/static/example-extensions/unsandboxed/when-key-pressed-restart.js b/static/example-extensions/unsandboxed/when-key-pressed-restart.js index 6f909400..0f087ceb 100644 --- a/static/example-extensions/unsandboxed/when-key-pressed-restart.js +++ b/static/example-extensions/unsandboxed/when-key-pressed-restart.js @@ -9,12 +9,12 @@ getInfo() { return { id: 'restartexampleunsandboxed', - name: 'Restart Threads Example', + name: Scratch.translate('Restart Threads Example'), blocks: [ { blockType: Scratch.BlockType.EVENT, opcode: 'whenPressed', - text: 'when [KEY] key pressed', + text: Scratch.translate('when [KEY] key pressed'), isEdgeActivated: false, // highlight-next-line shouldRestartExistingThreads: true, diff --git a/static/example-extensions/unsandboxed/when-key-pressed.js b/static/example-extensions/unsandboxed/when-key-pressed.js index e91b5103..92034365 100644 --- a/static/example-extensions/unsandboxed/when-key-pressed.js +++ b/static/example-extensions/unsandboxed/when-key-pressed.js @@ -9,12 +9,12 @@ getInfo() { return { id: 'eventexample2unsandboxed', - name: 'Event Block Example 2', + name: Scratch.translate('Event Block Example 2'), blocks: [ { blockType: Scratch.BlockType.EVENT, opcode: 'whenPressed', - text: 'when [KEY] key pressed', + text: Scratch.translate('when [KEY] key pressed'), isEdgeActivated: false, // required boilerplate // highlight-start arguments: { diff --git a/static/example-extensions/unsandboxed/when-space-key-pressed.js b/static/example-extensions/unsandboxed/when-space-key-pressed.js index da2d5f17..41ff3ccd 100644 --- a/static/example-extensions/unsandboxed/when-space-key-pressed.js +++ b/static/example-extensions/unsandboxed/when-space-key-pressed.js @@ -9,13 +9,13 @@ getInfo() { return { id: 'eventexampleunsandboxed', - name: 'Event Block Example', + name: Scratch.translate('Event Block Example'), blocks: [ // highlight-start { blockType: Scratch.BlockType.EVENT, opcode: 'whenSpacePressed', - text: 'when space key pressed', + text: Scratch.translate('when space key pressed'), isEdgeActivated: false // required boilerplate } // highlight-end diff --git a/static/example-extensions/unsandboxed/when.js b/static/example-extensions/unsandboxed/when.js index ea6fa2f2..266353fa 100644 --- a/static/example-extensions/unsandboxed/when.js +++ b/static/example-extensions/unsandboxed/when.js @@ -9,13 +9,13 @@ getInfo() { return { id: 'whenunsandboxed', - name: 'When', + name: Scratch.translate('When'), blocks: [ { // highlight-start blockType: Scratch.BlockType.HAT, opcode: 'when', - text: 'when [CONDITION]', + text: Scratch.translate('when [CONDITION]'), isEdgeActivated: false, // required boilerplate arguments: { CONDITION: {