Merge pull request #1478 from uraway/feature/translation-docs-javascript

[ja translation] TypeScript-Website/packages/documentation/copy/en/javascript/*.md

packages/documentation/copy/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)を試してみてください。

packages/documentation/copy/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)を参照してください。