Set up i8n for playground samples

packages/playground-examples/README.md

@@ -2,14 +2,51 @@
 
 The English examples can be found in [`en/`](en/).
 
+# TypeScript Example Code
+
+These samples are built for hyperlinking between each-other
+in a sandboxed environment like the TypeScript Playground.
+
+Each example aims to cover one or two specific features to
+either how JavaScript works in TypeScript, or features which
+TypeScript has added to the language.
+
+An example should make assumptions that the reader is in a
+monaco/IDE-like environment which has a TSServer running for
+to provide extra analysis. As well as a minor fluency in
+JavaScript.
+
+These examples are not set in stone, and we're open to new
+ideas. If you'd like to help out and speak more than one
+language, we'd love to see translations.
+
+## Adding a new example section
+
+Create a folder in the english section of the [`copy`](./copy) folder,
+then add sub-folders per section which you'd want to have as headers
+with 3-5 examples.
+
+## Adding a localization
+
+All localizations live inside the `copy` folder:
+
+- There must be a `sections.json` in the root of each language
+- A language is created by copying over an english example with the same path, and then translating it
+- Any examples not copied over fall back to the english version
+- You can change the name of an example for your language by having `//// { title: 'c0d3 fl0w', ... }` in the first line of the example
+
+Languages are compiled to TOC JSON files in [`generated`](./generated), one per lanaguge.
+
 # Deployment
 
 There is a table of contents JSON file which contains
 all the useful metadata about the hierarchy and sort
-order for the docs. 
+order for the docs.
 
 It's likely that we'll need to create this per translation
 in the future, but for now the table of contents will
 default to english.
 
-The script is in [`scripts/generateTOC.js`](scripts/generateTOC.js).
+The script is in [`scripts/generateTOC.js`](scripts/generateTOC.js), with  
+\output of the build process is then copied into the `typescriptlang-org`
+module under `static/js/examples` in [`scripts/copyFiles.js`](scripts/copyFiles.js).

packages/playground-examples/copy/en/sections.json

@@ -0,0 +1,47 @@
+{
+  "sections": [
+    {
+      "name": "JavaScript",
+      "id": "JavaScript",
+      "subtitle": "See how TypeScript improves day to day working with JavaScript with minimal additional syntax."
+    },
+    {
+      "name": "TypeScript",
+      "id": "TypeScript",
+      "subtitle": "Explore how TypeScript extends JavaScript to add more safety and tooling."
+    },
+    {
+      "name": "3.7",
+      "id": "3.7",
+      "subtitle": "See the <a href='https://devblogs.microsoft.com/typescript/announcing-typescript-3-7/'>Release notes</a>."
+    },
+    {
+      "name": "Playground",
+      "id": "Playground",
+      "subtitle": "Learn what has changed in this website."
+    }
+  ],
+
+  "sortedSubSections": [
+    // JS
+    "JavaScript Essentials",
+    "Functions with JavaScript",
+    "Working With Classes",
+    "Modern JavaScript",
+    "External APIs",
+    "Helping with JavaScript",
+    // TS
+    "Primitives",
+    "Type Primitives",
+    "Meta-Types",
+    "Language",
+    "Language Extensions",
+    // Examples
+    "Syntax and Messaging",
+    "Types and Code Flow",
+    "Fixits",
+    // Playground
+    "Config",
+    "Tooling"
+  ]
+}

packages/playground-examples/copy/leet/JavaScript/JavaScript Essentials/Code Flow.ts

@@ -0,0 +1,9 @@
+//// { title: 'c0d3 fl0w', order: 3, compiler: { strictNullChecks: true } }
+
+// How c0de fl0ws inside our JavaScript files can affect
+// the types throughout our programs.
+
+const users = [{ name: 'Ahmed' }, { name: 'Gemma' }, { name: 'Jon' }]
+
+// We're going to look to see if we can find a user named "jon".
+const jon = users.find(u => u.name === 'jon')

packages/playground-examples/copy/leet/JavaScript/JavaScript Essentials/Functions.ts

@@ -0,0 +1,10 @@
+//// { title: 'Func710ns', order: 2, compiler: { noImplicitAny: false } }
+
+// There are qu1te a few ways to declare a function in
+// JavaScript. Let's look at a function which adds two
+// numbers together:
+
+// Creates @ function in global scope called addOldSchool
+function addOldSchool(x, y) {
+  return x + y
+}

packages/playground-examples/copy/leet/JavaScript/JavaScript Essentials/Hello World.ts

@@ -0,0 +1,34 @@
+//// { title: 'h3ll0 w0rld', order: 0, compiler: { target: 1 } }
+
+// Welcome to the TypeScript playground. This site is a lot
+// like running a TypeScript project inside a web browser.
+
+// The playground makes it easy for you to safely experiment
+// with ideas in TypeScript by making it trivial to share
+// these projects. The URL for this page is everything
+// required to load the project for someone else.
+
+const hello = 'Hello'
+
+// You can see on the right the result of the TypeScript
+// compiler: this is vanilla JavaScript which can run on
+// browsers, servers or anywhere really.
+
+const world = 'World'
+
+// You can see how it makes tiny changes to the code, by
+// converting a "const" to a "var". This is one of the many
+// things TypeScript does to make it possible to run
+// anywhere JavaScript runs.
+
+console.log(hello + ' ' + world)
+
+// Now that you have an idea of how the playground works,
+// let's look at how TypeScript makes working with
+// JavaScript more fun. During this section we'll be trying
+// to keep as close to vanilla JavaScript as possible to
+// show how you can re-use existing knowledge.
+//
+// Click below to continue:
+//
+// example:objects-and-arrays

packages/playground-examples/copy/leet/JavaScript/JavaScript Essentials/Objects and Arrays.ts

@@ -0,0 +1,110 @@
+//// { title: '0bj3cts & 4rrays', order: 1, compiler: { strict: false } }
+
+// JavaScript objects are collections of values wrapped up
+// with named keys.
+
+const userAccount = {
+  name: 'Kieron',
+  id: 0,
+}
+
+// You can combine these to make larger, more complex
+// data-models.
+
+const pie = {
+  type: 'Apple',
+}
+
+const purchaseOrder = {
+  owner: userAccount,
+  item: pie,
+}
+
+// If you use your mouse to hover over some of these words
+// (try purchaseOrder above) you can see how TypeScript is
+// interpreting your JavaScript into labeled types.
+
+// Values can be accessed via the ".", so to get a
+// username for a purchase order:
+console.log(purchaseOrder.item.type)
+
+// If you hover your mouse over each part of the code
+// between the ()s, you can see TypeScript offering more
+// information about each part. Try re-writing this below:
+
+// Copy this in the next line, character by character:
+//
+//   purchaseOrder.item.type
+
+// TypeScript provides feedback to the playground
+// about what JavaScript objects are available in this
+// file and lets you avoid typoes and see additional
+// information without having to look it up in another place.
+
+// TypeScript also offers these same features to arrays.
+// Here's an array with just our purchase order above in it.
+
+const allOrders = [purchaseOrder]
+
+// If you hover on allOrders, you can tell it's an array
+// because the hover info ends with []. You can access the
+// first order by using square brackets with an index
+// (starting from zero).
+
+const firstOrder = allOrders[0]
+console.log(firstOrder.item.type)
+
+// An alternative way to get an object is via pop-ing the
+// array to remove objects. Doing this removes the object
+// from the array, and returns the object. This is called
+// mutating the array, because it changes the underlying
+// data inside it.
+
+const poppedFirstOrder = allOrders.pop()
+
+// Now allOrders is empty. Mutating data can be useful for
+// many things, but one way to reduce the complexity in your
+// codebases is to avoid mutation. TypeScript offers a way
+// to declare an array readonly instead:
+
+// Creates a type based on the shape of a purchase order:
+type PurchaseOrder = typeof purchaseOrder
+
+// Creates a readonly array of purchase orders
+const readonlyOrders: readonly PurchaseOrder[] = [purchaseOrder]
+
+// Yep! That's a bit more code for sure. There's four
+// new things here:
+//
+//  type PurchaseOrder - Declares a new type to TypeScript.
+//
+//  typeof - Use the type inference system to set the type
+//           based on the const which is passed in next.
+//
+//  purchaseOrder - Get the variable purchaseOrder and tell
+//                  TypeScript this is the shape of all
+//                  objects in the orders array.
+//
+//  readonly - This object does not support mutation, once
+//             it is created then the contents of the array
+//             will always stay the same.
+//
+// Now if you try to pop from the readonlyOrders, TypeScript
+// will raise an error.
+
+readonlyOrders.pop()
+
+// You can use readonly in all sorts of places, it's a
+// little bit of extra syntax here and there, but it
+// provides a lot of extra safety.
+
+// You can find out more about readonly:
+//  - [handbook link]
+//  - https://basarat.gitbooks.io/typescript/content/docs/types/readonly.html
+
+// And you can carry on learning about JavaScript and
+// TypeScript in the example on functions:
+// example:functions
+//
+// Or if you want to know more about immutability:
+// example:immutability

packages/playground-examples/copy/leet/sections.json

@@ -0,0 +1,47 @@
+{
+  "sections": [
+    {
+      "name": "J@va$cript",
+      "id": "JavaScript",
+      "subtitle": "See how Type$cr1pt improves day to day working with JavaScript with minimal additional syntax."
+    },
+    {
+      "name": "7ype5cript",
+      "id": "TypeScript",
+      "subtitle": "Explore h0w TypeScript extends JavaScript to add more safety and tooling."
+    },
+    {
+      "name": "3.7",
+      "id": "3.7",
+      "subtitle": "See the <a href='https://devblogs.microsoft.com/typescript/announcing-typescript-3-7/'>Release notes</a>."
+    },
+    {
+      "name": "P14yground",
+      "id": "Playground",
+      "subtitle": "Learn what has changed in this website."
+    }
+  ],
+
+  "sortedSubSections": [
+    // JS
+    "JavaScript Essentials",
+    "Functions with JavaScript",
+    "Working With Classes",
+    "Modern JavaScript",
+    "External APIs",
+    "Helping with JavaScript",
+    // TS
+    "Primitives",
+    "Type Primitives",
+    "Meta-Types",
+    "Language",
+    "Language Extensions",
+    // Examples
+    "Syntax and Messaging",
+    "Types and Code Flow",
+    "Fixits",
+    // Playground
+    "Config",
+    "Tooling"
+  ]
+}

packages/playground-examples/package.json

@@ -4,7 +4,7 @@
   "license": "MIT",
   "version": "1.0.0",
   "scripts": {
-    "build": "node scripts/generateTOC.js",
+    "build": "node scripts/generateTOC.js; node scripts/copyFiles.js",
     "test": "echo 'NOOP'",
     "bootstrap": "echo 'NOOP'"
   }

packages/playground-examples/scripts/copyFiles.js

@@ -0,0 +1,14 @@
+// @ts-check
+
+const { execSync } = require('child_process')
+const { join } = require('path')
+
+const copyDir = join(__dirname, '..', 'copy', '*')
+const jsonDir = join(__dirname, '..', 'generated', '*.json')
+const outDir = join(__dirname, '..', '..', 'typescriptlang-org', 'static', 'js', 'examples')
+
+// Move samples
+execSync(`cp -R ${copyDir} ${outDir}`)
+
+// Move the JSON files which are generated
+execSync(`cp ${jsonDir} ${outDir}`)