Merge pull request #3 from microsoft/main

Merge

Author: fegerar

.github/CODEOWNERS

@@ -1,11 +1,11 @@
 # See https://github.com/OSS-Docs-Tools/code-owner-self-merge#readme
 
 # Collaborators for Japanese Translation of the Website
-docs/playground/ja @sasurau4 @Quramy @Naturalclar @Takepepe [translation] [jp]
-docs/tsconfig/ja/**/*.md @sasurau4 @Quramy @Naturalclar @Takepepe [translation] [jp]
-docs/typescriptlang/ja/**/*.ts @sasurau4 @Quramy @Naturalclar @Takepepe [translation] [jp]
-docs/typescriptlang/ja.ts @sasurau4 @Quramy @Naturalclar @Takepepe [translation] [jp]
-docs/documentation/ja/**/*.md @sasurau4 @Quramy @Naturalclar @Takepepe [translation] [jp]
+docs/playground/ja @sasurau4 @Quramy @Naturalclar [translation] [jp]
+docs/tsconfig/ja/**/*.md @sasurau4 @Quramy @Naturalclar [translation] [jp]
+docs/typescriptlang/ja/**/*.ts @sasurau4 @Quramy @Naturalclar [translation] [jp]
+docs/typescriptlang/ja.ts @sasurau4 @Quramy @Naturalclar [translation] [jp]
+docs/documentation/ja/**/*.md @sasurau4 @Quramy @Naturalclar [translation] [jp]
 
 # Collaborators for Portuguese Translation of the Website
 docs/playground/pt @khaosdoctor @danilofuchs [translation] [pt]
@@ -29,11 +29,11 @@ docs/typescriptlang/zh.ts @Kingwl [translation] [zh]
 docs/documentation/zh/**/*.md @Kingwl [translation] [zh]
 
 # Collaborators for Korean Translation of the Website
-docs/playground/ko @Bumkeyy [translation] [ko]
-docs/tsconfig/ko/**/*.md @Bumkeyy [translation] [ko]
-docs/typescriptlang/ko/**/*.ts @Bumkeyy [translation] [ko]
-docs/typescriptlang/ko.ts @Bumkeyy [translation] [ko]
-docs/documentation/ko/**/*.md @Bumkeyy [translation] [ko]
+docs/playground/ko @Bumkeyy @yeonjuan @guyeol [translation] [ko]
+docs/tsconfig/ko/**/*.md @Bumkeyy @yeonjuan @guyeol [translation] [ko]
+docs/typescriptlang/ko/**/*.ts @Bumkeyy @yeonjuan @guyeol [translation] [ko]
+docs/typescriptlang/ko.ts @Bumkeyy @yeonjuan @guyeol [translation] [ko]
+docs/documentation/ko/**/*.md @Bumkeyy @yeonjuan @guyeol [translation] [ko]
 
 # Collaborators for Indonesian Translation of the Website
 docs/playground/id @jefrydco @nusendra @mazipan @mandaputtra [translation] [id]
@@ -57,8 +57,8 @@ docs/typescriptlang/pl.ts @msieroslawska @TomWebwalker [translation] [pl]
 docs/documentation/pl/**/*.md @msieroslawska @TomWebwalker [translation] [pl]
 
 # Collaborators for Italian Translation of the Website
-docs/playground/it @Nabster101 @BassDrop07 @PyGera @oliversalzburg [translation] [it]
-docs/tsconfig/it/**/*.md @Nabster101 @BassDrop07 @PyGera @oliversalzburg [translation] [it]
-docs/typescriptlang/it/**/*.ts @Nabster101 @BassDrop07 @PyGera @oliversalzburg [translation] [it]
-docs/typescriptlang/it.ts @Nabster101 @BassDrop07 @PyGera @oliversalzburg [translation] [it]
-docs/documentation/it/**/*.md @Nabster101 @BassDrop07 @PyGera @oliversalzburg [translation] [it]
+docs/playground/it @Nabster101 @DeltaPy @PyGera  [translation] [it]
+docs/tsconfig/it/**/*.md @Nabster101 @DeltaPy @PyGera  [translation] [it]
+docs/typescriptlang/it/**/*.ts @Nabster101 @DeltaPy @PyGera  [translation] [it]
+docs/typescriptlang/it.ts @Nabster101 @DeltaPy @PyGera  [translation] [it]
+docs/documentation/it/**/*.md @Nabster101 @DeltaPy @PyGera  [translation] [it]

.github/workflows/codeowners-merge.yml

@@ -1,6 +1,6 @@
 name: Codeowners merging
 on:
-  pull_request_target: { types: opened }
+  pull_request_target: { types: [ opened, synchronize, reopened] }
   issue_comment: { types: created }
   pull_request_review: { types: submitted }
 

README.md

@@ -15,7 +15,9 @@ yarn
 yarn pull-en
 
 # Optional: Verify your changes will correctly replace the english files
-yarn validate-paths
+yarn lint
+# Alternative: Run the lint watcher
+yarn lint --watch
 ```
 
 That's it, you've got a copy of all the documentation and now can write documentation which follows the existing patterns.
@@ -46,7 +48,8 @@ For example if you wanted to translate a new handbook page you would:
 - 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! 
+- Translate the file!
+- Validate your changes: `yarn lint` (or `yarn lint docs/documentation/it/handbook-v2/Basics.md`)
 - Create a pull request to this repo
 - Once merged, the translation will appear on the next website deploy
 
@@ -56,12 +59,14 @@ When a new language is created, we ask for a few people to become language owner
 
 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).
 
-#### Well tested
+#### Secure
 
 This repo has extensive CI to ensure that you can't accidentally break the TypeScript website. 
 
 There are local, fast checks that it won't break via `yarn test` and then the full TypeScript website test suite runs with the changes, and a website build is generated to ensure that nothing breaks.
 
+The checks may not seem obvious to an outsider, because the website is complex, so there is a watch mode which you can run via `yarn link --watch` to get instant feedback.
+
 # Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a

dangerfile.ts

@@ -1,9 +1,9 @@
 const markdownTranslate = require('@orta/markdown-translator')
-import {danger, message} from "danger"
+import {danger, markdown} from "danger"
 
 const go = async () => {
   const allMDFiles = [...danger.git.modified_files, ...danger.git.created_files].filter(f => f.endsWith(".md")).filter(f => f.split("/").length > 2)
-  console.log(allMDFiles)
+
 
   for (const file of allMDFiles) {
     const fileContents = await danger.github.utils.fileContents(file)
@@ -17,7 +17,12 @@ const go = async () => {
       region: "eastus"
     })
 
-    message(`## Translation of ${danger.github.utils.fileLinks([file])}\n\n${translation}`)
+    markdown(`<details open>
+<summary>Translation of ${danger.github.utils.fileLinks([file])}</summary>
+
+${translation}
+
+</details>`)
   };
 }
 

docs/documentation/ja/javascript/Creating DTS files From JS.md

@@ -0,0 +1,88 @@
+---
+title: .jsファイルから.d.tsファイルを生成する
+layout: docs
+permalink: /ja/docs/handbook/declaration-files/dts-from-js.html
+oneline: "JavaScriptプロジェクトでd.tsファイルを生成する方法"
+translatable: true
+---
+
+[TypeScript 3.7](/docs/handbook/release-notes/typescript-3-7.html#--declaration-and---allowjs)では、
+TypeScriptに、JSDoc構文を使ったJavaScriptから.d.tsファイルを生成するためのサポートが導入されました。
+
+この仕組みは、プロジェクトをTypeScriptに移行することなく、TypeScriptが備わったエディタの体験を自分のものにできるということを意味します。
+TypeScriptはほとんどのJSDocタグをサポートしています。リファレンスは[こちら](/docs/handbook/type-checking-javascript-files.html#supported-jsdoc)。
+
+## .d.tsファイルを出力するようにプロジェクトを設定する
+
+プロジェクトに.d.tsファイルの作成を追加するように設定するには、最大4つのステップを実行する必要があります:
+
+- dev dependenciesにTypeScriptを追加する
+- TypeScriptを設定するための`tsconfig.json`を追加する
+- TypeScriptコンパイラを実行して、JSファイルに対応するd.tsファイルを生成する
+- (任意) package.jsonを編集して型を参照できるようにする
+
+### TypeScriptを追加する
+
+こちらは、[インストールページ](/download)を参照してください。
+
+### TSConfig
+
+TSConfigはコンパイラのフラグを設定し、対象のファイルを宣言するためのjsoncファイルです。
+今回のケースでは、次のようなファイルが必要になるでしょう:
+
+```json5
+{
+  // プロジェクトに合わせて変更してください
+  include: ["src/**/*"],
+
+  compilerOptions: {
+    // JSファイルは通常、ソースファイルとして無視されますが、
+    // ここではJSファイルを読み込むようにTypeScriptに指示します
+    allowJs: true,
+    // d.tsファイルを生成します
+    declaration: true,
+    // コンパイラを実行すると
+    // d.tsファイルのみ出力されます
+    emitDeclarationOnly: true,
+    // 型はこのディレクトリに出力されます
+    // このオプションを削除すると
+    // .jsファイルの隣に.d.tsファイルが置かれます
+    outDir: "dist",
+  },
+}
+```
+
+オプションについては、[tsconfigリファレンス](/reference)で詳しく知ることができます。
+TSConfigファイルを使用する代替手段としてCLIがあります。次は上記のTSConfigファイルの設定と同じふるまいをするCLIコマンドです。
+
+```sh
+npx typescript src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types
+```
+
+## コンパイラを実行する
+
+実行方法については[インストールページ](/download)を参照してください。
+プロジェクトの`.gitignore`にファイルが指定してある場合は、これらのファイルがパッケージに含まれていることを確認しましょう。
+
+## package.jsonを編集する
+
+TypeScriptは、.d.tsファイルを見つけるためのステップを追加し、`package.json`の中でNodeのモジュール解決を再現します。
+大まかには、モジュール解決は任意のフィールドである`"types"`フィールドをチェックし、次に`"main"`フィールド、そして最後にルートの`index.d.ts`を試します。
+
+| Package.json              | デフォルトの.d.tsの場所           |
+| :------------------------ | :----------------------------- |
+| "types"フィールドがない      | "main"をチェックし、次にindex.d.ts|
+| "types": "main.d.ts"      | main.d.ts                      |
+| "types": "./dist/main.js" | ./main/main.d.ts               |
+
+もし存在しなければ、次は"main"が使用されます
+
+| Package.json              | デフォルトの.d.tsの場所     |
+| :----------------------- | :------------------------ |
+| "main"フィールドがない      | index.d.ts                |
+| "main":"index.js"        | index.d.ts                |
+| "main":"./dist/index.js" | ./dist/index.d.ts         |
+
+## Tips
+
+.d.tsファイルにテストを記述したいなら、[tsd](https://github.com/SamVerschueren/tsd)を試してみてください。

docs/documentation/ja/javascript/Intro to JS with TS.md

@@ -0,0 +1,70 @@
+---
+title: TypeScriptを活用したJSプロジェクト
+layout: docs
+permalink: /ja/docs/handbook/intro-to-js-ts.html
+oneline: TypeScriptを使ってJavaScriptファイルに型チェックを追加する方法
+translatable: true
+---
+
+TypeScriptの型システムがコードベースを扱う際には、様々な厳密さのレベルがあります:
+
+- JavaScriptのコードを使った推論のみに基づく型システム
+- [JSDoc](/docs/handbook/jsdoc-supported-types.html)によるJavaScriptの段階的な型付け
+- JavaScriptファイルにおける`// @ts-check`の使用
+- TypeScriptコード
+- [`strict`](/tsconfig#strict)を有効にしたTypeScript
+
+それぞれのステップはより安全な型システムへの動きを表していますが、すべてのプロジェクトがそのレベルでの検証を必要としているわけではありません。
+
+## JavaScriptと併用するTypeScript
+
+こちらは、オートコンプリートやシンボルへのジャンプといった機能や、リネームなどのリファクタリングツールを提供するためにTypeScriptを使用しているエディタを使う場合です。
+[homepage](/)では、TypeScriptプラグインを備えているエディタをリストしています。
+
+## JSDocを使ってJSで型ヒントを提供する
+
+`.js`ファイルでは、多くの場合型を推測することが可能です。型が推測できない場合、JSDoc構文を使って指定することができます。
+
+宣言の前でJSDocのアノテーションを使い、その宣言の型を設定します。例えば:
+
+```js twoslash
+/** @type {number} */
+var x;
+
+x = 0; // OK
+x = false; // OK?!
+```
+
+サポートしているJSDocパターンの全リストは[JSDocがサポートする型](/docs/handbook/jsdoc-supported-types.html)にあります。
+
+## `@ts-check`
+
+前述のコードサンプルの最後の行はTypeScriptではエラーとなりますが、JSプロジェクトのデフォルトではエラーを発生させません。
+JavaScriptファイルでエラーを有効化するには、`.js`ファイルの最初の行に`// @ts-check`を追加して、TypeScriptにエラーを発生させるようにします。
+
+```js twoslash
+// @ts-check
+// @errors: 2322
+/** @type {number} */
+var x;
+
+x = 0; // OK
+x = false; // エラー
+```
+
+エラーを追加したいJavaScriptファイルがたくさんある場合は、[`jsconfig.json`](/docs/handbook/tsconfig-json.html)を使用するように変更しましょう。
+ファイルに`// @ts-nocheck`コメントをつけることで、ファイルのチェックを省略することができます。
+
+TypeScriptはあなたが納得できないようなエラーを発生させるかもしれませんが、その場合は前の行に`// @ts-ignore`または`// @ts-expect-error`を追加することで、特定の行のエラーを無視することができます。
+
+```js twoslash
+// @ts-check
+/** @type {number} */
+var x;
+
+x = 0; // OK
+// @ts-expect-error
+x = false; // エラー
+```
+
+JavaScriptがTypeScriptによってどのように解釈されるかについて知りたい場合は、[TSの型がJSをチェックする方法](/docs/handbook/type-checking-javascript-files.html)を参照してください。