Gandi-IDE · zhllucky · May 19, 2023
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -1,96 +1,129 @@
-# ccw-user-extensions
+# ccw-extensions-template
 
-- [ccw-user-extensions](#ccw-user-extensions)
-  * [What for](#what-for)
-  * [How to jump in](#how-to-jump-in)
-    + [Normal remote extension (for anyone)](#normal-remote-extension--for-anyone-)
-    + [CCW approved extension (for CCW collaborator)](#ccw-approved-extension--for-ccw-collaborator-)
-    + [Apply for CCW collaborator](#apply-for-ccw-collaborator)
-  * [How to develop](#how-to-develop)
-    + [Define a extension](#define-a-extension)
-      - [normal remote extension](#normal-remote-extension)
-      - [CCW approved extension](#ccw-approved-extension)
-    + [Test your extension](#test-your-extension)
-      - [normal remote extension](#normal-remote-extension-1)
-      - [CCW approved extension](#ccw-approved-extension-1)
-    + [Asset standard](#asset-standard)
+[中文文档](./README.zh.md)
+If you don't want to use new templates,please refer to this [document](./src/original/README.md)
 
-<small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>
+[TOC]
 
-## What for
-This repo is for CCW Creator who wants make and test their own extensions.
-## How to jump in
-There are two ways to develop and test your extensions.
-### Normal remote extension (for anyone)
-You can build your blocks and test them.
+<br/>
+<br/>
 
-You can use all javascript capacity to do what you want.
+## What is for
 
-There only have one limit: normal remote extension will be running in a sandbox and unable to access vm or runtime utilities.
-### CCW approved extension (for CCW collaborator)
+This branch is a template for developing extensions for Gandi IDE, an in-browser game engine, a mod of [Scratch](https://scratch.mit.edu/).
 
-As a CCW collaborator, your can push code into this repo.
+## Requirements
 
-Extensions in this repo will have full access to vm and runtime utilities allows you build advanced block for all CCW Creator.
+1. a modern PC or Mac
+2. any web development IDE you like.(highly recommended VSCode)
+3. install 'git'
+4. install 'node.js' version > 12.16
+5. install 'yarn' latest version
 
-When your complete testing,you can apply for publish extensions to CCW Extension Library. All CCW Creator can use it in their project.
-### Apply for CCW collaborator
-- fork this repo and submit your PR。
-## How to develop 
+## How to create a new extension
 
-### Define a extension
-#### normal remote extension
+1. create a new folder
+2. fork and git clone this branch
+3. run command 'yarn'
+4. run command 'yarn extension-kit create'
+5. follow the instructions to create extension files
+6. now you will see your new extension files in 'src/extension/{{developer}}/{{extensionId}}' folder
+7. open 'src/extension/{{developer}}/{{extensionId}}/index.ts' file to start coding
 
-[.example/normal-ext.js](https://github.com/CCW-Site/ccw-user-extension/blob/main/example/normal-ext.js)
+    Tips: don not modify any files if you don't know what those files are.
 
-#### CCW approved extension
+## Localization
 
-[.example/ccw-approved-ext.js](https://github.com/CCW-Site/ccw-user-extension/blob/main/example/ccw-approved-ext.js)
-### Test your extension
-#### normal remote extension
-if your work on a normal remote extension, you can upload your extension js file to any http server and make sure it can be accessed in open network.
+run command 'yarn extension l10n {extension_path}'
 
-when complete above moves, use below url in browser(recommend Chrome)
-```
-https://www.ccw.site/creator?extension=${your_file_url}
-```
+like 'yarn extension l10n src/extension/Arkos/file_helper'
 
-For example
-```
-https://www.ccw.site/creator?extension=https://ccw-user-extension.ccw.site/example/normal-ext.js
-```
-Extensions will be added to the bottom of block menu if there is no error in your code.
+l10n file will be created in path 'src/extension/Arkos/file_helper/l10n'
 
-#### CCW approved extension
-Push code and a bot will deploy your commit to a http server automatically. The URL is like below.
+it will analyze your code and generate l10n key-value into zh-cn.json and en.json like below
 
-The automatic deploy url format is like below
 ```
-https://ccw-user-extension.ccw.site/${your_folder}/${jsFile}
+{
+  test: 'test[A][B][C]',
+  commandArugA: 'commandArugA',
+  menuOpt1: 'menuOpt1',
+  menuOpt12: 'menuOpt12',
+  commandArguB: 'commandArguB',
+  targetReporter: 'targetReporter[A][B][C]',
+  globalReporter: 'globalReporter[A][B][C]',
+  conditionalBlocks: 'conditionalBlocks[A][B][C]',
+  loopBlocks: 'loopBlocks[A][B][C]',
+  eventBlocks: 'eventBlocks[A][B][C]',
+  hatBlocks: 'hatBlocks[A][B][C]'
+}
 ```
 
-When completing the above moves, use the URL below in your browser(recommend Chrome).
-```
-https://www.ccw.site/creator?ext=https://ccw-user-extension.ccw.site/${your_folder}/${jsFile}
-```
-For example
-```
-https://www.ccw.site/creator?ext=https://ccw-user-extension.ccw.site/example/ccw-approved-ext.js
+keys and arguments placeholder are mapping from block code, you just need translate it.
+
+## How to test
+
+1. run 'yarn dev' to start the local dev server. Keep it running if no errors are shown.
+2. open Gandi, choose [Custom Extension] in Extension Library.
+3. paste URL 'http://localhost:9999/static/js/main.js' to the input and confirm
+4. the extension will be shown in the Custom category.
+
+## How to publish
+
+1. submit to Gandi team
+    - make a PR to this Branch
+    - when PR is reviewed and merged, you extension will show in Gandi Extension Library
+2. deploy by yourself, use URL load
+    - run 'yarn build'
+    - upload 'dist' folder to any http or CDN server
+    - make sure the file is accessible by URL after upload
+
+        recommend CDN service: <https://www.jsdelivr.com/?docs=gh>
+    - add Custom Extension by URL
+
+## How to create a block
+
+use function in 'BlockUtil', all functions
+
+```js
+    export default {
+        createReporter, 
+        createBool, 
+        createCommand, 
+        createConditional, 
+        createLoop, 
+        createButton, 
+        createEvent, 
+        createHat, 
+        createMenu, 
+        createDynamicMenu, 
+        createArgument
+    }
 ```
 
-Extensions will be registed in Extension Library. You must add it by hand before you use it.
+you can find usage simple in 'index.ts' after use create command
 
-### Asset standard
+
+## Runtime API
+
+[TODO]
+
+#### Gandi Community API
+
+[TODO]
+
+## Asset
+
+You can change the cover and icon in the 'assets' folder.
+The image type and resolution should be correct, as shown below:
 
 Extension cover
-type: png/jpg/svg
+type: jpg
 size: 600 × 372 px
 
-Extension block icon
-type: svg
+Extension icon
+type: png
 size: 80 x 80 px
 
-Extension menu icon
-type: svg
-size: 80 x 80 px
+## Q & A
 
+If you have any other questions, feel free to leave a message and discuss it in the issues section.
diff --git a/README.zh.md b/README.zh.md
@@ -0,0 +1,128 @@
+# ccw-extensions-template
+
+[English documentation](./README.md)
+如果你不想使用新模版，可以移步至[文档](./src/original/README.zh.md)
+[TOC]
+
+<br/>
+<br/>
+
+## 用途
+
+该分支是为 Gandi IDE 开发扩展而创建的模板， Gandi IDE 是一个基于浏览器的游戏引擎，是 [Scratch](https://scratch.mit.edu/) 的一个修改版本。
+此文档主要是针对使用新模板进行开发的文档，若需要使用官方模板开发请查看此文档
+
+## 开发要求
+
+1. 一台现代的 PC 或 Mac
+2. 任何你喜欢的 Web 开发 IDE （强烈推荐使用 VSCode ）
+3. 安装 'git'
+4. 安装 'node.js' version > 12.16
+5. 安装 'yarn'
+
+## 如何创建一个新扩展
+
+1. 创建一个新文件夹
+2. fork 并克隆该分支
+3. 运行命令 'yarn'
+4. 运行命令 'yarn extension-kit create'
+5. 按照指示创建扩展文件
+6. 现在你将在 'src/extension/{{developer}}/{{extensionId}}' 文件夹中看到你的新扩展文件
+7. 打开 'src/extension/{{developer}}/{{extensionId}}/index.ts' 文件开始编写代码
+
+    Tips: 如果有的文件你不知道是做什么的，那么请勿修改它.
+
+## 国际化翻译
+
+运行命令 'yarn extension l10n {extension_path}'
+
+例如 'yarn extension l10n src/extension/Arkos/file_helper'
+
+l10n文件将被创建在路径 'src/extension/Arkos/file_helper/l10n' 中
+
+它会分析你的代码并生成中英文的 l10n 键值，如下所示
+
+```
+{
+  test: 'test[A][B][C]',
+  commandArugA: 'commandArugA',
+  menuOpt1: 'menuOpt1',
+  menuOpt12: 'menuOpt12',
+  commandArguB: 'commandArguB',
+  targetReporter: 'targetReporter[A][B][C]',
+  globalReporter: 'globalReporter[A][B][C]',
+  conditionalBlocks: 'conditionalBlocks[A][B][C]',
+  loopBlocks: 'loopBlocks[A][B][C]',
+  eventBlocks: 'eventBlocks[A][B][C]',
+  hatBlocks: 'hatBlocks[A][B][C]'
+}
+```
+
+key 和 arguments 占位符与块代码进行映射，你只需要进行翻译。
+
+## 如何进行测试
+
+1. 运行 'yarn dev' 启动本地开发服务器。如果没有显示错误，请保持运行状态。
+2. 打开Gandi，在扩展库中选择 [Custom Extension]。
+3. 将 URL 'http://localhost:9999/static/js/main.js' 粘贴到输入框并确认。
+4. 该扩展将显示在自定义类别中。
+
+## 如何发布
+
+1. 提交给Gandi团队
+    - 在该分支上创建一个 PR
+    - 当 PR 被审核并合并后，你的扩展将显示在 Gandi 扩展库中
+2. 自行部署，使用URL加载
+    - 运行 'yarn build'
+    - 将 'dist' 文件夹上传至任何HTTP或CDN服务器
+    - 确保上传后的文件可以通过URL访问
+
+        推荐使用CDN服务：https://www.jsdelivr.com/?docs=gh
+    - 通过URL添加自定义扩展
+
+## 如何创建一个代码块
+
+使用 'BlockUtil' 中的函数，包括以下所有函数：
+
+```js
+    export default {
+        createReporter, 
+        createBool, 
+        createCommand, 
+        createConditional, 
+        createLoop, 
+        createButton, 
+        createEvent, 
+        createHat, 
+        createMenu, 
+        createDynamicMenu, 
+        createArgument
+    }
+```
+
+使用 create 命令后，您可以在 'index.ts' 文件中找到简单的使用示例。
+
+## Runtime API
+
+[TODO]
+
+#### Gandi Community API
+
+[TODO]
+
+## 资源文件
+
+您可以在 'assets' 文件夹中更改封面和图标。
+图片类型和分辨率应该正确，如下所示：
+
+扩展封面
+type: jpg
+size: 600 × 372 px
+
+扩展图标
+type: png
+size: 80 x 80 px
+
+## Q & A
+
+如果你有任何其他问题，欢迎在issues中进行留言讨论