Merge pull request #2 from microsoft/test_ci

Test CI

Author: Orta Therox

.github/workflows/CI.yml

@@ -8,10 +8,8 @@ jobs:
     steps:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
-      - run: yarn 
-      - run: yarn pull-en
-      - run: yarn docs-sync validate
-
+      - run: yarn
+      - run: yarn docs-sync validate-against-en
 
   site-builds:
     runs-on: ubuntu-latest
@@ -25,7 +23,8 @@ jobs:
       - uses: actions/checkout@v1
       - run: yarn
 
-      # Clone the TS website
+      # Clone the TS website, basically:
+      # git clone https://github.com/microsoft/TypeScript-Website website
       - name: Checkout tools repo
         uses: actions/checkout@v2
         with:
@@ -34,17 +33,25 @@ jobs:
 
       # Both the microsoft/TypeScript-Website & 1 - don't really need to be there, but 
       # this migrates the translated docs into the website
-      - run: yarn docs-sync pull microsoft/TypeScript-Website 1 --from-cwd . --to-cwd TypeScript-Website
+      - run: yarn docs-sync pull microsoft/TypeScript-Website 1 --from-cwd . --to-cwd website
 
       # Get dependencies for building the ebooks
       - run: sudo apt-get update
       - run: sudo apt install calibre
 
-      - run: cd website
       - run: yarn install
         env:
           YARN_CHECKSUM_BEHAVIOR: ignore
+        working-directory: ./website
+
 
       # Verify the website build
       - run: yarn bootstrap
+        working-directory: ./website
+
       - run: yarn workspace typescriptlang-org build
+        working-directory: ./website
+
+      # Verify the website build
+      - run: yarn test
+        working-directory: ./website

README.md

@@ -2,7 +2,7 @@
 
 A repo for handling localized versions of the TypeScript website content
 
-### How this works
+### Setting up
 
 ```sh
 git clone https://github.com/microsoft/TypeScript-Website-Localizations
@@ -11,14 +11,50 @@ cd TypeScript-Website-Localizations
 # Setup
 yarn
 
-# Optional: Grab the English files
+# Optional: Grab the English files to make translation easier
 yarn pull-en
+
+# Optional: Verify your changes will correctly replace the english files
+yarn validate-paths
 ```
 
 That's it, you've got a copy of all the documentation and now can write documentation which follows the existing patterns.
 
-More docs to come.
+### How translations work 
+
+The TypeScript website handles translations by having language specific files with matching filepaths:
+
+E.g: [`/packages/documentation/copy/en/reference/JSX.md`](https://github.com/microsoft/TypeScript-website/blob/68a4f67ed5f396228eeb6d0309b51bcfb19d31a1/packages/documentation/copy/en/reference/JSX.md#L1)
+
+Has existing translations in different languages:
+
+```sh
+/packages/documentation/copy/id/reference/JSX.md
+/packages/documentation/copy/ja/reference/JSX.md
+/packages/documentation/copy/pt/reference/JSX.md
+```
+
+Same path, just switched `en` for `id`, `ja` & `pt`.
+
+#### This repo
+
+This repo contains all of the non-English locale files. It means you can clone and translate without all the infrastructure overhead of the pretty complex TypeScript-Website. 
+
+For example if you wanted to translate a new handbook page you would:
+
+- Clone this repo (see above)
+- Pull in the English files `yarn pull-en` (these will be gitignored)
+- Find your english file: `docs/documentation/en/handbook-v2/Basics.md`
+- Recreate the same folder path in your language: `docs/documentation/it/handbook-v2/Basics.md`
+- Translate the file! 
+- Create a pull request to this repo
+- Once merged, the translation will appear on the next website deploy
+
+#### Language owners
+
+When a new language is created, we ask for a few people to become language owners. These owners are able to merge pull requests to files in their language via [code-owner-self-merge](https://github.com/OSS-Docs-Tools/code-owner-self-merge) in a pull request. They will be pinged on PRs which affect them, you can see the flow in PRs like [this](https://github.com/microsoft/TypeScript-Website/pull/1478) or [this](https://github.com/microsoft/TypeScript-Website/pull/1458).
 
+The TypeScript team generally only know English, and can answer clarifying questions if needed! For quick questions, you can use the `ts-website-translation` channel in the [TypeScript Discord](https://discord.gg/typescript).
 
 # Contributing