start type declarations, prepare handbook

Author: mk360

docs/documentation/fr/handbook-v2/The Handbook.md

@@ -0,0 +1,59 @@
+---
+title: The TypeScript Handbook
+layout: docs
+permalink: /docs/handbook/intro.html
+oneline: Your first step to learn TypeScript
+handbook: "true"
+---
+
+## About this Handbook
+
+Over 20 years after its introduction to the programming community, JavaScript is now one of the most widespread cross-platform languages ever created. Starting as a small scripting language for adding trivial interactivity to webpages, JavaScript has grown to be a language of choice for both frontend and backend applications of every size. While the size, scope, and complexity of programs written in JavaScript has grown exponentially, the ability of the JavaScript language to express the relationships between different units of code has not. Combined with JavaScript's rather peculiar runtime semantics, this mismatch between language and program complexity has made JavaScript development a difficult task to manage at scale.
+
+The most common kinds of errors that programmers write can be described as type errors: a certain kind of value was used where a different kind of value was expected. This could be due to simple typos, a failure to understand the API surface of a library, incorrect assumptions about runtime behavior, or other errors. The goal of TypeScript is to be a static typechecker for JavaScript programs - in other words, a tool that runs before your code runs (static) and ensures that the types of the program are correct (typechecked).
+
+If you are coming to TypeScript without a JavaScript background, with the intention of TypeScript being your first language, we recommend you first start reading the documentation on either the [Microsoft Learn JavaScript tutorial](https://docs.microsoft.com/javascript/) or read [JavaScript at the Mozilla Web Docs](https://developer.mozilla.org/docs/Web/JavaScript/Guide).
+If you have experience in other languages, you should be able to pick up JavaScript syntax quite quickly by reading the handbook.
+
+## How is this Handbook Structured
+
+The handbook is split into two sections:
+
+- **The Handbook**
+
+  The TypeScript Handbook is intended to be a comprehensive document that explains TypeScript to everyday programmers. You can read the handbook by going from top to bottom in the left-hand navigation.
+
+  You should expect each chapter or page to provide you with a strong understanding of the given concepts. The TypeScript Handbook is not a complete language specification, but it is intended to be a comprehensive guide to all of the language's features and behaviors.
+
+  A reader who completes the walkthrough should be able to:
+
+  - Read and understand commonly-used TypeScript syntax and patterns
+  - Explain the effects of important compiler options
+  - Correctly predict type system behavior in most cases
+
+  In the interests of clarity and brevity, the main content of the Handbook will not explore every edge case or minutiae of the features being covered. You can find more details on particular concepts in the reference articles.
+
+- **Reference Files**
+
+  The reference section below the handbook in the navigation is built to provide a richer understanding of how a particular part of TypeScript works. You can read it top-to-bottom, but each section aims to provide a deeper explanation of a single concept - meaning there is no aim for continuity.
+
+### Non-Goals
+
+The Handbook is also intended to be a concise document that can be comfortably read in a few hours. Certain topics won't be covered in order to keep things short.
+
+Specifically, the Handbook does not fully introduce core JavaScript basics like functions, classes, and closures. Where appropriate, we'll include links to background reading that you can use to read up on those concepts.
+
+The Handbook also isn't intended to be a replacement for a language specification. In some cases, edge cases or formal descriptions of behavior will be skipped in favor of high-level, easier-to-understand explanations. Instead, there are separate reference pages that more precisely and formally describe many aspects of TypeScript's behavior. The reference pages are not intended for readers unfamiliar with TypeScript, so they may use advanced terminology or reference topics you haven't read about yet.
+
+Finally, the Handbook won't cover how TypeScript interacts with other tools, except where necessary. Topics like how to configure TypeScript with webpack, rollup, parcel, react, babel, closure, lerna, rush, bazel, preact, vue, angular, svelte, jquery, yarn, or npm are out of scope - you can find these resources elsewhere on the web.
+
+## Get Started
+
+Before getting started with [The Basics](/docs/handbook/2/basic-types.html), we recommend reading one of the following introductory pages. These introductions are intended to highlight key similarities and differences between TypeScript and your favored programming language, and clear up common misconceptions specific to those languages.
+
+- [TypeScript for New Programmers](/docs/handbook/typescript-from-scratch.html)
+- [TypeScript for JavaScript Programmers](/docs/handbook/typescript-in-5-minutes.html)
+- [TypeScript for OOP Programmers](/docs/handbook/typescript-in-5-minutes-oop.html)
+- [TypeScript for Functional Programmers](/docs/handbook/typescript-in-5-minutes-func.html)
+
+Otherwise, jump to [The Basics](/docs/handbook/2/basic-types.html) or grab a copy in [Epub](/assets/typescript-handbook.epub) or [PDF](/assets/typescript-handbook.pdf) form.

docs/documentation/fr/handbook-v2/Type Declarations.md

@@ -0,0 +1,100 @@
+---
+title: Type Declarations
+layout: docs
+permalink: /fr/docs/handbook/2/type-declarations.html
+oneline: "Comment TypeScript fournit du typage pour du code JavaScript."
+---
+
+Jusque-là, nous avons présenté des concepts basiques de TypeScript en utilisant des fonctionnalités présentes dans tous les moteurs JavaScript.
+De nos jours, JavaScript contient beaucoup de librairies qui accomplissent des tâches communes.
+Avoir du typage sur les parties d'application qui _ne font pas_ partie de votre code améliorera grandement votre expérience TypeScript.
+Where do these types come from?
+
+## À quoi ressemblent les déclarations de types ?
+
+Supposons que vous avez ce code :
+
+```ts twoslash
+// @errors: 2339
+const k = Math.max(5, 6);
+const j = Math.mix(7, 8);
+```
+
+Comment TypeScript a-t-il su que `max` existe, mais pas `mix`, même sans que l'implémentation de `Math` fasse partie de votre code ?
+
+Il existe des _fichiers de déclarations_ qui décrivent ces objets pré-existants.
+Un fichier de déclarations fournit une manière de _déclarer_ l'existence de certains types ou certaines valeurs, sans leur fournir d'implémentation.
+
+## Fichiers `.d.ts`
+
+TypeScript a deux types principaux de fichiers.
+Les fichiers `.ts` sont des fichiers d'_implémentation_, qui contiennent du code exécutable.
+Ce sont les fichiers qui émettent des fichiers `.js` en sortie. C'est là que vous écrirez votre code.
+
+Les fichiers `.d.ts` sont des fichiers de _déclarations_, qui ne contiennent _que_ des informations de types.
+Ces fichiers n'émettent pas de sortie `.js`; ils servent uniquement à la vérification de types.
+Nous apprendrons comment écrire nos propres fichiers de déclarations plus tard.
+
+## Définitions de Types Pré-existantes
+
+TypeScript possède des fichiers de déclarations pour toutes les APIs standard pré-existantes dans les moteurs JavaScript.
+Ils contiennent, par exemple, les propriétés des types `string` ou `function`, les objets globaux comme `Math` et `Object`, ainsi que leurs types associés.
+Par défaut, TypeScript contient également les types des éléments du navigateur, comme `window` et `document`; que l'on appelle collectivement les APIs de DOM (_DOM APIs_).
+
+Ces fichiers suivent la convention de nommage `lib.[quelque chose].d.ts`.
+Si vous ouvrez un fichier suivant ce nommage, vous saurez que c'est un élément pré-existant de la plateforme, qui ne contient pas de code.
+
+### Option `target`
+
+Les méthodes, propriétés, et fonctions disponibles varient, dans les faits, en fonction de la _version_ de JavaScript que votre code exécute.
+Par exemple, la méthode `startsWith` des chaînes de caractères est disponible à partir de la 6ème version de JavaScript (_EcmaScript 6_).
+
+Il est important de connaître quelle version de JavaScript est exécutée, car vous ne voulez pas utiliser d'APIs disponibles sur des versions plus récentes.
+C'est l'un des rôles de l'option de compilateur [`target`](/tsconfig#target).
+
+TypeScript helps with this problem by varying which `lib` files are included by default based on your [`target`](/tsconfig#target) setting.
+For example, if [`target`](/tsconfig#target) is `ES5`, you will see an error if trying to use the `startsWith` method, because that method is only available in `ES6` or later.
+
+### `lib` setting
+
+The [`lib`](/tsconfig#lib) setting allows more fine-grained control of which built-in declaration files are considered available in your program.
+See the documentation page on [`lib`](/tsconfig#lib) for more information.
+
+## External Definitions
+
+For non-built-in APIs, there are a variety of ways you can get declaration files.
+How you do this depends on exactly which library you're getting types for.
+
+### Bundled Types
+
+If a library you're using is published as an npm package, it may include type declaration files as part of its distribution already.
+You can read the project's documentation to find out, or simply try importing the package and see if TypeScript is able to automatically resolve the types for you.
+
+If you're a package author considering bundling type definitions with your package, you can read our guide on [bundling type definitions](/docs/handbook/declaration-files/publishing.html#including-declarations-in-your-npm-package).
+
+### DefinitelyTyped / `@types`
+
+The [DefinitelyTyped repository](https://github.com/DefinitelyTyped/DefinitelyTyped/) is a centralized repo storing declaration files for thousands of libraries.
+The vast majority of commonly-used libraries have declaration files available on DefinitelyTyped.
+
+Definitions on DefinitelyTyped are also automatically published to npm under the `@types` scope.
+The name of the types package is always the same as the name of the underlying package itself.
+For example, if you installed the `react` npm package, you can install its corresponding types by running
+
+```sh
+npm install --save-dev @types/react
+```
+
+TypeScript automatically finds type definitions under `node_modules/@types`, so there's no other step needed to get these types available in your program.
+
+### Your Own Definitions
+
+In the uncommon event that a library didn't bundle its own types and didn't have a definition on DefinitelyTyped, you can write a declaration file yourself.
+See the appendix [Writing Declaration Files](/docs/handbook/declaration-files/introduction.html) for a guide.
+
+If you want to silence warnings about a particular module without writing a declaration file, you can also quick declare the module as type `any` by putting an empty declaration for it in a `.d.ts` file in your project.
+For example, if you wanted to use a module named `some-untyped-module` without having definitions for it, you would write:
+
+```ts twoslash
+declare module "some-untyped-module";
+```