Merge remote-tracking branch 'upstream/master'

.gitignore

@@ -27,4 +27,7 @@ yarn-error.log*
 # generated using scripts/download-sponsors.json
 website/data/sponsors.json
 
+website/i18n/*
+website/translated_docs
+
 package-lock.json

README.md

@@ -2,10 +2,8 @@
 
 This is the source for the [babeljs.io](https://babeljs.io) website; feel free to suggest changes to our docs!
 
-> We're just switched over to a new site using https://docusaurus.io so there might be a few issues to fix
-
-- Current site: `master` branch is deployed to https://babeljs.io
-- Old site: `old-site` branch is deployed to https://old.babeljs.io
+- Current: `master` branch is deployed to https://babeljs.io
+- Old: `old-site` branch is deployed to https://old.babeljs.io
 
 ### Setup
 
@@ -26,10 +24,10 @@ You might want to make yourself familiar with [docusaurus](https://docusaurus.io
 #### Versioned docs
 
 - `/docs` - the files in here are responsible for the "next" version at https://babeljs.io/docs/en/next.
-- `/website/versioned_docs/version-7.0.0` - these are the docs for the currently published version at https://babeljs.io/docs/en
+- `/website/versioned_docs/version-7.1.0` - these are the docs for the currently published version at https://babeljs.io/docs/en
 
 To make a fix to the published site you must edit the corresponding markdown file at both folders.
 
 #### Looking for support?
 
-For questions and support on contributing please join our [Slack community](https://slack.babeljs.io/), channel `#website` or directly [here](https://babeljs.slack.com/messages/website/).
+For questions and support on contributing please join our [Slack community](https://slack.babeljs.io/), channel `#website` or directly [here](https://babeljs.slack.com/messages/website).

_redirects

@@ -62,6 +62,13 @@
 /docs/plugins/minify-*              /docs/en/babel-plugin-minify-:splat
 /docs/plugins/external-helpers/     /docs/en/babel-plugin-external-helpers
 
+/docs/en/babel-plugin-transform-async-generator-functions       /docs/en/babel-plugin-proposal-async-generator-functions
+/docs/en/babel-plugin-transform-class-properties                /docs/en/babel-plugin-proposal-class-properties
+/docs/en/babel-plugin-transform-decorators                      /docs/en/babel-plugin-proposal-decorators
+/docs/en/babel-plugin-transform-do-expressions                  /docs/en/babel-plugin-proposal-do-expressions
+/docs/en/babel-plugin-transform-export-extensions               /docs/en/babel-plugin-proposal-export-namespace
+/docs/en/babel-plugin-transform-object-rest-spread              /docs/en/babel-plugin-proposal-object-rest-spread
+
 /docs/plugins/check-es2015-constants/ /docs/en/babel-plugin-check-es2015-constants
 /docs/plugins/transform-es2015-constants /docs/en/babel-plugin-check-es2015-constants
 /docs/plugins/undeclared-variables-check/ /docs/en/babel-plugin-undeclared-variables-check

docs/caveats.md

@@ -21,7 +21,7 @@ There is also the `loose` option for some of these plugins.
 ## Classes
 
 Built-in classes such as `Date`, `Array`, `DOM` etc cannot be properly subclassed
-due to limitations in ES5 (for the [es2015-classes](plugin-transform-es2015-classes.md) plugin).
+due to limitations in ES5 (for the [transform-classes](plugin-transform-classes.md) plugin).
 You can try to use [babel-plugin-transform-builtin-extend](https://github.com/loganfsmyth/babel-plugin-transform-builtin-extend) based on `Object.setPrototypeOf` and `Reflect.construct`, but it also has some limitations.
 
 ## ES5
@@ -44,7 +44,7 @@ this is widely supported but you may run into problems with much older browsers.
 around.
 
 For classes that have `super`s, the super class won't resolve correctly. You can
-get around this by enabling the `loose` option in the [es2015-classes](plugin-transform-es2015-classes.md) plugin.
+get around this by enabling the `loose` option in the [transform-classes](plugin-transform-classes.md) plugin.
 
 ### Getters/setters (8 and below)
 

docs/cli.md

@@ -1,7 +1,7 @@
 ---
 id: babel-cli
 title: @babel/cli
-sidebar_label: babel-cli
+sidebar_label: cli
 ---
 
 Babel comes with a built-in CLI which can be used to compile files from the command line.
@@ -126,15 +126,15 @@ npx babel --out-file script-compiled.js < script.js
 Use the `--plugins` option to specify plugins to use in compilation
 
 ```sh
-npx babel script.js --out-file script-compiled.js --plugins=transform-runtime,transform-es2015-modules-amd
+npx babel script.js --out-file script-compiled.js --plugins=@babel/proposal-class-properties,@babel/transform-modules-amd
 ```
 
 ### Using Presets
 
 Use the `--presets` option to specify plugins to use in compilation
 
 ```sh
-npx babel script.js --out-file script-compiled.js --presets=es2015,react
+npx babel script.js --out-file script-compiled.js --presets=@babel/preset-env,@babel/flow
 ```
 
 ### Ignoring .babelrc

docs/code-frame.md

@@ -1,7 +1,7 @@
 ---
 id: babel-code-frame
 title: @babel/code-frame
-sidebar_label: babel-code-frame
+sidebar_label: code-frame
 ---
 
 ## Install

docs/config-files.md

@@ -27,30 +27,16 @@ which were traditionally quite painful to configure in Babel 6.x.
 
 The primary downside of this project-wide config is that, because it relies on the working
 directory, it can be more painful to use in monorepos if the working directory is not the monorepo root.
-For example, if you have
-
-```text
-babel.config.js
-packages/
-  mod1/
-    package.json
-    src/index.js
-  mod2/
-    package.json
-    src/index.js
-```
-and the individual packages are responsible for running their builds (and their working
-directory for Babel is the individual packages), the `babel.config.js` file will not be automatically
-loaded, and users will be required to set the path to it manually.
+See the [monorepo](#monorepos) documentation for examples of how to use config files in that context.
 
 Project-wide configs can also be disabled by setting ["configFile"](options.md#configfile) to `false`.
 
 ## File-relative configuration
 
 Babel loads `.babelrc` (and `.babelrc.js` / `package.json#babel`) files by searching up the
-directory structure starting from the ["filename"](options.md#filename) being compiled. This can
-be powerful because it allows you to create independent configurations for subsections of
-a repository. File-relative configurations are also [merged](options.md#merging) over top of
+directory structure starting from the ["filename"](options.md#filename) being compiled (limited by the caveats below).
+This can be powerful because it allows you to create independent configurations for subsections of
+a package. File-relative configurations are also [merged](options.md#merging) over top of
 project-wide config values, making them potentially useful for specific overrides, though that can
 also be accomplished through ["overrides"](options.md#overrides).
 
@@ -60,7 +46,14 @@ There are a few edge cases to consider when using a file-relative config:
 * The ["filename"](options.md#filename) being compiled must be inside of
   ["babelrcRoots"](options.md#babelrcroots) packages, or else searching will be skipped entirely.
 
-File-relative configs can also be disable by setting ["babelrc"](options.md#babelrc) to `false`.
+These caveats mean that:
+* `.babelrc` files _only_ apply to files within their own package
+* `.babelrc` files in packages that aren't Babel's 'root' are ignored unless you opt in
+  with ["babelrcRoots"](options.md#babelrcroots).
+
+See the [monorepo](#monorepos) documentation for more discussion on how to configure monorepos that have many packages.
+
+File-relative configs can also be disabled by setting ["babelrc"](options.md#babelrc) to `false`.
 
 ### 6.x vs 7.x `.babelrc` loading
 
@@ -100,6 +93,144 @@ section above, this may then require explicitly setting ["configFile"](options.m
 since Babel will not find the config file if the working directory isn't correct.
 
 
+## Monorepos
+
+Monorepo-structured repositories usually contain many packages, which means that they frequently
+run into the caveats mentioned in [file-relative configuration](#file-relative-configuration)
+and config file loading in general. This section is aimed at helping users understand how
+to approach monorepo configuration.
+
+With monorepo setups, the core thing to understand is that Babel treats your working directory
+as its logical ["root"](options.md#root), which causes problems if you want to run Babel
+tools within a specific sub-package without having Babel apply to the repo as a whole.
+
+Separately, it is also important to decide if you want to use [`.babelrc`](#file-relative-configuration)
+files or just a central [`babel.config.js`](#project-wide-configuration). [`.babelrc`](#file-relative-configuration)
+files are not required for subfolder-specific configuration like they were in Babel 6, so
+often they are not needed in Babel 7, in favor of a [`babel.config.js`](#project-wide-configuration).
+
+
+### Root `babel.config.js` files
+
+The first step in any monorepo structure should be to create a
+[`babel.config.js`](#project-wide-configuration) file in repository root. This
+establishes Babel's core concept of the base directory of your repository. Even if you want to use
+[`.babelrc`](#file-relative-configuration) files to configure each separate package, it is important
+to have as a place for repo-level options.
+
+You can often place all of your repo configuration in the root [`babel.config.js`](#project-wide-configuration).
+With ["overrides"](options.md#overrides), you can easily specify configuration that only applies to
+certain subfolders of your repository, which can often be easier to follow than creating many
+`.babelrc` files across the repo.
+
+The first issue you'll likely run into is that by default, Babel expects to load [`babel.config.js`](#project-wide-configuration)
+files from the directory set as its ["root"](options.md#root), which means that if you create
+a [`babel.config.js`](#project-wide-configuration), but run Babel inside an individual package, e.g.
+
+```bash
+cd packages/some-package;
+babel src -d dist
+```
+the ["root"](options.md#root) Babel is using in that context is _not_ your monorepo root,
+and it won't be able to find the [`babel.config.js`](#project-wide-configuration) file.
+
+If all of your build scripts run relative to your repository root, things should already work, but if
+you are running your Babel compilation process from within a subpackage, you need to tell Babel where
+to look for the config. There are a few ways to do that, but the recommended way is
+the ["rootMode"](options.md#rootmode) option with `"upward"`, which will make Babel search from
+the working directory upward looking for your [`babel.config.js`](#project-wide-configuration) file,
+and will use its location as the ["root"](options.md#root) value.
+
+One helpful way to test if your config is being detected is to place a `console.log()` call
+inside of it. Since it is a JS file, the log will execute the first time Babel loads it.
+
+How you set this value varies by project, but here are a few examples:
+
+#### CLI
+```bash
+babel --root-mode upward src -d lib
+```
+
+#### @babel/register
+```js
+require("@babel/register")({
+  rootMode: "upward"
+});
+```
+
+#### Webpack
+```js
+module: {
+  rules: [{
+    loader: "babel-loader",
+    options: {
+      rootMode: "upward",
+    }
+  }]
+}
+```
+
+#### Jest
+Jest is often installed at the root of the monorepo and may not require configuration,
+but if it is installed per-package it can unfortunately be more complex to configure.
+
+The main part is creating a custom jest transformer file that wraps `babel-jest`'s default
+behavior in order to set the option, e.g.
+```js
+module.exports = require("babel-jest").createTransformer({
+  rootMode: "upward",
+});
+```
+and with that saved somewhere, you'd then use that file in the place of `babel-jest` in
+your Jest options via the [transform option](https://jestjs.io/docs/en/configuration#transform-object-string-string):
+```json
+"transform": {
+  "^.+\\.jsx?$": "./path/to/wrapper.js"
+},
+```
+so all JS files will be processed with your version of `babel-jest` with the option enabled.
+
+#### Others
+
+There are tons of tools, but at the core of it is that they need the `rootMode` option enabled
+if the working directory is not already the monorepo root.
+
+
+### Subpackage `.babelrc` files
+
+Similar to the the way `babel.config.js` files are required to be in the ["root"](options.md#root),
+`.babelrc` files must be in the root _package_, by default. This means that, the same way the
+working directory affects `babel.config.js` loading, it also affects `.babelrc` loading.
+
+Assuming you've already gotten your `babel.config.js` file loaded properly as discussed above,
+Babel will only process `.babelrc` files inside that root package (and not subpackages),
+so given for instance
+
+```text
+package.json
+babel.config.js
+packages/
+  mod/
+    package.json
+    .babelrc
+    index.js
+```
+compiling the `packages/mod/index.js` file will not load `packages/mod/.babelrc` because
+this `.babelrc` is within a sub-package, not the root package.
+
+To enable processing of that `.babelrc`, you will want to use the ["babelrcRoots"](options.md#babelrcroots)
+option from inside your `babel.config.js` file to do
+
+```js
+babelrcRoots: [
+  ".",
+  "packages/*",
+],
+```
+so that Babel will consider all `packages/*` packages as allowed to load `.babelrc` files,
+along with the original repo root.
+
+
 ## Config Format
 
 The format of individual config files themselves separates into JS files vs [JSON5](https://json5.org/) files.
@@ -130,7 +261,7 @@ module.exports = function(api) {
 }
 ```
 
-The `api` object exposes everthing Babel itself exposes from its index module, along with
+The `api` object exposes everything Babel itself exposes from its index module, along with
 config-file specific APIs:
 
 ### `api.version`
@@ -146,7 +277,7 @@ there is that it makes caching harder. Babel wants to avoid re-executing the
 config function every time a file is compiled, because then it would also need to
 re-execute any plugin and preset functions referenced in that config.
 
-The avoid this, Babel expects users of config functions to tell it how to manage
+To avoid this, Babel expects users of config functions to tell it how to manage
 caching within a config file.
 
 * `api.cache.forever()` - Permacache the computed config and never call the function again.

docs/configuration.md

@@ -27,7 +27,9 @@ All Babel API [options](options.md) are allowed. However, if the option requires
 Create a file called `babel.config.js` with the following content at the root of your project (where the `package.json` is).
 
 ```js
-module.exports = function () {
+module.exports = function (api) {
+  api.cache(true);
+
   const presets = [ ... ];
   const plugins = [ ... ];
 
@@ -38,7 +40,7 @@ module.exports = function () {
 }
 ```
 
-Checkout the [`babel.config.js` documentation](config-files.md#project-wide-configuration) to see more configuration options.
+Check out the [`babel.config.js` documentation](config-files.md#project-wide-configuration) to see more configuration options.
 
 ## `.babelrc`
 
@@ -51,7 +53,7 @@ Create a file called `.babelrc` with the following content in your project.
 }
 ```
 
-Checkout the [.babelrc documentation](config-files.md#file-relative-configuration) to see more configuration options.
+Check out the [.babelrc documentation](config-files.md#file-relative-configuration) to see more configuration options.
 
 ### `package.json`
 
@@ -70,7 +72,7 @@ Alternatively, you can choose to specify your [`.babelrc`](#babelrc) config from
 
 ### `.babelrc.js`
 
-The configuration is the same than [`.babelrc`](#babelrc), apart than you can write it using JavaScript.
+The configuration is the same as [`.babelrc`](#babelrc), but you can write it using JavaScript.
 
 ```js
 const presets = [ ... ];
@@ -98,7 +100,7 @@ module.exports = { presets, plugins };
 babel --plugins @babel/plugin-transform-arrow-functions script.js
 ```
 
-Checkout the [babel-cli documentation](cli.md) to see more configuration options.
+Check out the [babel-cli documentation](cli.md) to see more configuration options.
 
 ## Using the API (`@babel/core`)
 
@@ -108,4 +110,4 @@ require("@babel/core").transform("code", {
 });
 ```
 
-Checkout the [babel-core documentation](core.md) to see more configuration options.
+Check out the [babel-core documentation](core.md) to see more configuration options.

docs/core.md

@@ -1,7 +1,7 @@
 ---
 id: babel-core
 title: @babel/core
-sidebar_label: babel-core
+sidebar_label: core
 ---
 
 ```javascript