README

Author: orta

.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
@@ -52,3 +50,7 @@ jobs:
 
       - run: yarn workspace typescriptlang-org build
         working-directory: ./website
+
+      # Verify the website build
+      - run: yarn test
+        working-directory: ./web

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
 

yarn.lock

@@ -3,11 +3,12 @@
 
 
 "@oss-docs/sync@*":
-  version "0.3.1"
-  resolved "https://registry.yarnpkg.com/@oss-docs/sync/-/sync-0.3.1.tgz#9d39d81f0bb91373c0180ab7a3ac4c47f7d2fd5f"
-  integrity sha512-y9SNwKA701CgWBQRCzeYw54bmDy9DzhCueMGpZquWj+m1yOc+g/OH0cPVpYT2+zPv+gAc35zW21yDi+ujlG8Uw==
+  version "0.4.1"
+  resolved "https://registry.yarnpkg.com/@oss-docs/sync/-/sync-0.4.1.tgz#b5f9aa339cd9d8daf891d1fa4bebd56520d09e2a"
+  integrity sha512-6pjnvUJ6EVAs8AeAKcvAAfFAODzpspgjo5ufuP04jT1Y8IZ9LLOqkPdo3xPMDb/TJPzcinFf1/DjaaZUvaEb3A==
   dependencies:
     cachedir "^2.3.0"
+    chalk "^4.1.0"
     cross-spawn "^7.0.1"
     gunzip-maybe "^1.4.1"
     mvdir "^1.0.21"
@@ -19,7 +20,7 @@ ansi-regex@^5.0.0:
   resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-5.0.0.tgz#388539f55179bf39339c81af30a654d69f87cb75"
   integrity sha512-bY6fj56OUQ0hU1KjFNDQuJFezqKdrAyFdIevADiqrWHwSlbmBNMHp5ak2f40Pm8JTFyM2mqxkG6ngkHO11f/lg==
 
-ansi-styles@^4.0.0:
+ansi-styles@^4.0.0, ansi-styles@^4.1.0:
   version "4.3.0"
   resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-4.3.0.tgz#edd803628ae71c04c85ae7a0906edad34b648937"
   integrity sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==
@@ -65,6 +66,14 @@ cachedir@^2.3.0:
   resolved "https://registry.yarnpkg.com/cachedir/-/cachedir-2.3.0.tgz#0c75892a052198f0b21c7c1804d8331edfcae0e8"
   integrity sha512-A+Fezp4zxnit6FanDmv9EqXNAi3vt9DWp51/71UEhXukb7QUuvtv9344h91dyAxuTLoSYJFU299qzR3tzwPAhw==
 
+chalk@^4.1.0:
+  version "4.1.0"
+  resolved "https://registry.yarnpkg.com/chalk/-/chalk-4.1.0.tgz#4e14870a618d9e2edd97dd8345fd9d9dc315646a"
+  integrity sha512-qwx12AxXe2Q5xQ43Ac//I6v5aXTipYrSESdOgzrN+9XjgEpyjpKuvSGaN4qE93f7TQTlerQQ8S+EQ0EyDoVL1A==
+  dependencies:
+    ansi-styles "^4.1.0"
+    supports-color "^7.1.0"
+
 chownr@^1.1.1:
   version "1.1.4"
   resolved "https://registry.yarnpkg.com/chownr/-/chownr-1.1.4.tgz#6fc9d7b42d32a583596337666e7d08084da2cc6b"
@@ -154,6 +163,11 @@ gunzip-maybe@^1.4.1:
     pumpify "^1.3.3"
     through2 "^2.0.3"
 
+has-flag@^4.0.0:
+  version "4.0.0"
+  resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-4.0.0.tgz#944771fd9c81c81265c4d6941860da06bb59479b"
+  integrity sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==
+
 ieee754@^1.1.13:
   version "1.2.1"
   resolved "https://registry.yarnpkg.com/ieee754/-/ieee754-1.2.1.tgz#8eb7a10a63fff25d15a57b001586d177d1b0d352"
@@ -339,6 +353,13 @@ strip-ansi@^6.0.0:
   dependencies:
     ansi-regex "^5.0.0"
 
+supports-color@^7.1.0:
+  version "7.2.0"
+  resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-7.2.0.tgz#1b7dcdcb32b8138801b3e478ba6a51caa89648da"
+  integrity sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==
+  dependencies:
+    has-flag "^4.0.0"
+
 tar-fs@^2.1.0:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/tar-fs/-/tar-fs-2.1.1.tgz#489a15ab85f1f0befabb370b7de4f9eb5cbe8784"