docs(en): merging all conflicts

docschina · Nov 6, 2024 · 6ad6af1 · 6ad6af1
2 parents a90f03b + bd8ae6f
commit 6ad6af1
Show file tree

Hide file tree

Showing 120 changed files with 4,286 additions and 2,007 deletions.
diff --git a/_redirects b/_redirects
@@ -64,22 +64,29 @@ https://babel.netlify.com/* https://babeljs.io/:splat 301!
 /docs/plugins/minify-*              /docs/babel-plugin-minify-:splat
 /docs/plugins/external-helpers/     /docs/babel-plugin-external-helpers
 
+# Removed packages
+/docs/babel-highlight /docs/babel-code-frame#migrating-from-babelhighlight
+
 # Plugins renamed from -proposal- to -transform-
-/docs/babel-plugin-proposal-class-static-block                  /docs/babel-plugin-transform-class-static-block
-/docs/babel-plugin-proposal-private-property-in-object          /docs/babel-plugin-transform-private-property-in-object
-/docs/babel-plugin-proposal-class-properties                    /docs/babel-plugin-transform-class-properties
-/docs/babel-plugin-proposal-private-methods                     /docs/babel-plugin-transform-private-methods
-/docs/babel-plugin-proposal-numeric-separator                   /docs/babel-plugin-transform-numeric-separator
-/docs/babel-plugin-proposal-logical-assignment-operators        /docs/babel-plugin-transform-logical-assignment-operators
-/docs/babel-plugin-proposal-nullish-coalescing-operator         /docs/babel-plugin-transform-nullish-coalescing-operator
-/docs/babel-plugin-proposal-optional-chaining                   /docs/babel-plugin-transform-optional-chaining
-/docs/babel-plugin-proposal-json-strings                        /docs/babel-plugin-transform-json-strings
-/docs/babel-plugin-proposal-optional-catch-binding              /docs/babel-plugin-transform-optional-catch-binding
-/docs/babel-plugin-proposal-async-generator-functions           /docs/babel-plugin-transform-async-generator-functions
-/docs/babel-plugin-proposal-object-rest-spread                  /docs/babel-plugin-transform-object-rest-spread
-/docs/babel-plugin-proposal-unicode-property-regex              /docs/babel-plugin-transform-unicode-property-regex
-/docs/babel-plugin-proposal-unicode-sets-regex                  /docs/babel-plugin-transform-unicode-sets-regex
-/docs/babel-plugin-proposal-export-namespace-from               /docs/babel-plugin-transform-export-namespace-from
+/docs/babel-plugin-proposal-class-static-block                      /docs/babel-plugin-transform-class-static-block
+/docs/babel-plugin-proposal-private-property-in-object              /docs/babel-plugin-transform-private-property-in-object
+/docs/babel-plugin-proposal-class-properties                        /docs/babel-plugin-transform-class-properties
+/docs/babel-plugin-proposal-private-methods                         /docs/babel-plugin-transform-private-methods
+/docs/babel-plugin-proposal-numeric-separator                       /docs/babel-plugin-transform-numeric-separator
+/docs/babel-plugin-proposal-dynamic-import                          /docs/babel-plugin-transform-dynamic-import
+/docs/babel-plugin-proposal-logical-assignment-operators            /docs/babel-plugin-transform-logical-assignment-operators
+/docs/babel-plugin-proposal-nullish-coalescing-operator             /docs/babel-plugin-transform-nullish-coalescing-operator
+/docs/babel-plugin-proposal-optional-chaining                       /docs/babel-plugin-transform-optional-chaining
+/docs/babel-plugin-proposal-json-strings                            /docs/babel-plugin-transform-json-strings
+/docs/babel-plugin-proposal-optional-catch-binding                  /docs/babel-plugin-transform-optional-catch-binding
+/docs/babel-plugin-proposal-async-generator-functions               /docs/babel-plugin-transform-async-generator-functions
+/docs/babel-plugin-proposal-object-rest-spread                      /docs/babel-plugin-transform-object-rest-spread
+/docs/babel-plugin-proposal-unicode-property-regex                  /docs/babel-plugin-transform-unicode-property-regex
+/docs/babel-plugin-proposal-unicode-sets-regex                      /docs/babel-plugin-transform-unicode-sets-regex
+/docs/babel-plugin-proposal-export-namespace-from                   /docs/babel-plugin-transform-export-namespace-from
+/docs/babel-plugin-proposal-duplicate-named-capturing-groups-regex  /docs/babel-plugin-transform-duplicate-named-capturing-groups-regex
+/docs/babel-plugin-proposal-regexp-modifiers                        /docs/babel-plugin-transform-regexp-modifiers
+/docs/babel-plugin-proposal-json-modules                            /docs/babel-plugin-transform-json-modules
 
 # Legacy redirects
 /docs/en/babel-plugin-transform-decorators                      /docs/babel-plugin-proposal-decorators
@@ -92,8 +99,10 @@ https://babel.netlify.com/* https://babeljs.io/:splat 301!
 /docs/en/next/tools/*               /setup
 
 # Blog rewrites
+/7.26.0 /blog/2024/10/25/7.26.0
+/7.25.0 /blog/2024/07/26/7.25.0
 /7.24.0 /blog/2024/02/28/7.24.0
-/7.23.0 /blog/2023/09/25/7.22.0
+/7.23.0 /blog/2023/09/25/7.23.0
 /7.22.0 /blog/2023/05/26/7.22.0
 /7.21.0 /blog/2023/02/20/7.21.0
 /7.20.0 /blog/2022/10/27/7.20.0
@@ -139,3 +148,6 @@ https://babel.netlify.com/* https://babeljs.io/:splat 301!
 # Docusaurus v1 compat
 
 /docs/en/* /docs/:splat
+
+# CircleCI CORS
+/circleci/api/* https://circleci.com/api/v1.1/project/github/babel/babel/:splat 200
diff --git a/docs/assumptions.md b/docs/assumptions.md
@@ -434,8 +434,6 @@ class Child extends Parent {
     "mutableTemplateObject": true,
     "noClassCalls": true,
     "noDocumentAll": true,
-    "noObjectSuper": true,
-    "noUndeclaredVariablesCheck": true,
     "objectRestNoSymbols": true,
     "privateFieldsAsProperties": true,
     "pureGetters": true,

diff --git a/docs/code-frame.md b/docs/code-frame.md
@@ -11,6 +11,12 @@ npm install --save-dev @babel/code-frame
 
 ## Usage
 
+### `codeFrameColumns`
+
+The `codeFrameColumns` function allows you to decorate a code snipped with line numbers and with a marker pointing to a specific location.
+
+It will also optionally highlight your code, defaulting to what is supported by the output terminal.
+
 ```js title="JavaScript"
 import { codeFrameColumns } from "@babel/code-frame";
 
@@ -68,33 +74,33 @@ console.log(result);
   5 | };
 ```
 
-## Options
+#### Options
 
-### `highlightCode`
+##### `highlightCode`
 
 `boolean`, defaults to `false`.
 
 Toggles syntax highlighting the code as JavaScript for terminals.
 
-### `linesAbove`
+##### `linesAbove`
 
 `number`, defaults to `2`.
 
 Adjust the number of lines to show above the error.
 
-### `linesBelow`
+##### `linesBelow`
 
 `number`, defaults to `3`.
 
 Adjust the number of lines to show below the error.
 
-### `forceColor`
+##### `forceColor`
 
 `boolean`, defaults to `false`.
 
 Enable this to forcibly syntax highlight the code as JavaScript (for non-terminals); overrides `highlightCode`.
 
-### `message`
+##### `message`
 
 `string`, otherwise nothing
 
@@ -109,6 +115,76 @@ the code frame.
 3 | };
 ```
 
+### `highlight`
+
+The `highlight` function adds syntax highlighting to a code snipped, to be displayed in a terminal.
+
+```js title="JavaScript"
+import { highlight } from "@babel/code-frame";
+
+const code = `class Foo {
+  constructor()
+}`;
+
+const result = highlight(code);
+
+console.log(result);
+```
+
+```js title="JavaScript"
+class Foo {
+  constructor()
+}
+```
+
+## Migrating from `@babel/highlight`
+
+The `highlight` functionality was originally split in its own package, `@babel/highlight`.
+
+You can migrate as follows:
+<table>
+<thead>
+<tr>
+<th>Using <code>@babel/highlight</code></th>
+<th>Using <code>@babel/code-frame</code></th>
+</tr>
+</thead>
+<tbody><tr><td>
+
+```js title="JavaScript"
+import highlight from "@babel/highlight";
+
+highlight(text, { forceColor: true });
+```
+
+</td><td>
+
+```js title="JavaScript"
+import { highlight } from "@babel/code-frame";
+
+highlight(text);
+```
+
+</td></tr><tr><td>
+
+```js title="JavaScript"
+import highlight from "@babel/highlight";
+
+highlight(text);
+```
+
+</td><td>
+
+```js title="JavaScript"
+import { highlight } from "@babel/code-frame";
+
+process.stdout.hasColors() ? highlight(text) : text;
+```
+
+</td></tr></tbody></table>
+
+:::babel7
+
 ## Upgrading from prior versions
 
 Prior to version 7, the only API exposed by this module was for a single line and optional column pointer. The old API will now log a deprecation warning.
@@ -151,3 +227,5 @@ const result = codeFrameColumns(rawLines, location, {
 
 console.log(result);
 ```
+
+:::
diff --git a/docs/features-timeline.md b/docs/features-timeline.md
@@ -9,6 +9,25 @@ Which major new features did we introduce in each Babel version? This page inclu
 Additionally, use this timeline to track some other important efforts, such as the [babel-polyfills](https://github.com/babel/babel-polyfills) project.
 
 <ol class="timeline-container">
+<li data-date="Oct 2024">
+
+## Babel 7.26.0
+
+[blog post](https://babeljs.io/blog/2024/10/25/7.26.0)
+
+- Enable the [regular expression modifiers](https://github.com/tc39/proposal-regexp-modifiers/) Stage 4 proposal by default
+- Enable parsing of the [import attributes](https://github.com/tc39/import-attributes/) Stage 4 proposal by default
+
+</li>
+<li data-date="Jul 2024">
+
+## Babel 7.25.0
+
+[blog post](https://babeljs.io/blog/2024/07/26/7.25.0)
+
+- Enable the Stage 4 [duplicated named capturing groups](https://github.com/tc39/proposal-duplicate-named-capturing-groups/) proposal by default
+
+</li>
 <li data-date="Feb 2024">
 
 ## Babel 7.24.0

diff --git a/docs/generator.md b/docs/generator.md
@@ -3,7 +3,7 @@ id: babel-generator
 title: "@babel/generator"
 ---
 
-> Turns an AST into code.
+> Turns Babel AST into code.
 
 ## Install
 
@@ -33,13 +33,33 @@ const output = generate(
 The symbols like white spaces or new line characters are not preserved in the AST. When Babel generator prints code from the AST, the output format is not guaranteed.
 :::
 
+### Parser plugins support
+Babel generator supports all the listed [Babel parser plugins](./parser.md#plugins) except `estree`. Note that parser plugins do not transform the code. For example,
+if you pass JSX `<div></div>` to babel generator, the result will still contain the `div` JSX element.
+
+```js title="JavaScript"
+import { parse } from "@babel/parser";
+import generate from "@babel/generator";
+
+const code = "const Example = () => <div>example</div>";
+const ast = parse(code, { plugins: ["jsx" ] });
+
+const output = generate(
+  ast,
+);
+
+// true
+output.includes("<div>");
+```
+
 ## Options
 
 <details>
   <summary>History</summary>
 
 | Version | Changes |
 | --- | --- |
+| v7.26.0 | Added `experimental_preserveFormat` |
 | v7.22.0 | Added `importAttributesKeyword` |
 | v7.21.0 | Added `inputSourceMap` |
 </details>
@@ -74,6 +94,17 @@ Options for source maps:
 | sourceRoot     | string           |         | A root for all relative URLs in the source map                                                                         |
 | sourceFileName | string           |         | The filename for the source code (i.e. the code in the `code` argument). This will only be used if `code` is a string. |
 
+Experimental options:
+
+:::warning
+The behavior of experimental options could have breaking changes in _minor_ versions.
+:::
+
+| name                        | type    | default | description | experimental reason |
+| --------------------------- | ------- | ------- | ----------- | ------------------- |
+| experimental_preserveFormat | boolean | `false` | When set to `true`, the generator will try to preserve location of all the nodes and tokens that are present both in the input and output code. To use this option, you currently need to enable the `retainLines: true` generator option, and the `tokens: true` and `createParenthesizedExpressions: true` parser options. | This option will graduate to stable once it supports a mode that does not require preserving line numbers, but just relative positions of tokens. |
+
+
 ## AST from Multiple Sources
 
 In most cases, Babel does a 1:1 transformation of input-file to output-file. However,

diff --git a/docs/helper-environment-visitor.md b/docs/helper-environment-visitor.md
@@ -74,7 +74,7 @@ if (path.isMethod()) {
 
 Suppose we are migrating from vanilla JavaScript to ES Modules. Now that the `this` keyword is equivalent to `undefined` at the top level of an ESModule ([spec](https://tc39.es/ecma262/#sec-module-environment-records-getthisbinding)), we want to replace all top-level `this` to [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis):
 
-```js title=input.js
+```js title="input.js"
 // replace this expression to `globalThis.foo = "top"`
 this.foo = "top";
 

diff --git a/docs/highlight.md b/docs/highlight.md
diff --git a/docs/index.md b/docs/index.md
@@ -30,7 +30,11 @@ For an awesome tutorial on compilers, check out [the-super-tiny-compiler](https:
 
 Babel 通过语法转换(syntax transformer)支持最新版本的 JavaScript。
 
+<<<<<<< HEAD
 这些 [plugins](plugins.md) 允许你**现在**就使用新语法，而无需等待浏览器的支持。查看我们的 [使用指南](usage.md) 以开始使用。
+=======
+These [plugins](plugins-list.md) allow you to use new syntax, **right now** without waiting for browser support. Check out our [usage guide](usage.md) to get started.
+>>>>>>> bd8ae6f66fd7910d57e86fa2b89f5b22e324ca2d
 
 ## JSX 和 React
 

diff --git a/docs/node.md b/docs/node.md
@@ -72,15 +72,29 @@ NODE_NO_READLINE=1 rlwrap --always-readline npx babel-node
 ### Usage
 
 ```sh title="Shell"
-babel-node [options] [ -e script | script.js ] [arguments]
+babel-node [options] [ -e script | [--] script.js ] [arguments]
 ```
 
+:::babel7
+
 When arguments for user script have names conflicting with node options, double dash placed before script name can be used to resolve ambiguities
 
 ```sh title="Shell"
 npx babel-node --inspect --presets @babel/preset-env -- script.js --inspect
 ```
 
+:::
+
+:::babel8
+
+Options for Node.js and Babel must be placed before the file name, while arguments for the script (that will be available as `process.argv`) must be placed after.
+
+```sh title="Shell"
+npx babel-node --arg-for-babel script.js --arg-for-script.js
+```
+
+:::
+
 ### Options
 
 | Option                 | Default                           | Description                                                                                                                                                                                    |