From c9a50b1b563d4bab49a61a2e6feb060ad31bd944 Mon Sep 17 00:00:00 2001 From: thejameskylebot Date: Fri, 12 Feb 2016 00:48:22 -0500 Subject: [PATCH] [i18n] Sync Translations --- translations/af/plugin-handbook.md | 210 ++++++++--------- translations/af/user-handbook.md | 138 ++++++------ translations/ar/plugin-handbook.md | 210 ++++++++--------- translations/ar/user-handbook.md | 138 ++++++------ translations/ca/README.md | 12 +- translations/ca/plugin-handbook.md | 214 +++++++++--------- translations/ca/user-handbook.md | 172 +++++++------- translations/cs/plugin-handbook.md | 210 ++++++++--------- translations/cs/user-handbook.md | 138 ++++++------ translations/da/plugin-handbook.md | 210 ++++++++--------- translations/da/user-handbook.md | 138 ++++++------ translations/de/plugin-handbook.md | 210 ++++++++--------- translations/de/user-handbook.md | 138 ++++++------ translations/el/README.md | 12 +- translations/el/plugin-handbook.md | 288 ++++++++++++------------ translations/el/user-handbook.md | 166 +++++++------- translations/es-ES/README.md | 2 +- translations/es-ES/plugin-handbook.md | 216 +++++++++--------- translations/es-ES/user-handbook.md | 162 ++++++------- translations/fi/plugin-handbook.md | 210 ++++++++--------- translations/fi/user-handbook.md | 138 ++++++------ translations/fr/plugin-handbook.md | 210 ++++++++--------- translations/fr/user-handbook.md | 138 ++++++------ translations/he/plugin-handbook.md | 210 ++++++++--------- translations/he/user-handbook.md | 138 ++++++------ translations/hu/plugin-handbook.md | 210 ++++++++--------- translations/hu/user-handbook.md | 138 ++++++------ translations/id-ID/plugin-handbook.md | 210 ++++++++--------- translations/id-ID/user-handbook.md | 138 ++++++------ translations/it/plugin-handbook.md | 210 ++++++++--------- translations/it/user-handbook.md | 138 ++++++------ translations/ja/README.md | 10 +- translations/ja/plugin-handbook.md | 214 +++++++++--------- translations/ja/user-handbook.md | 152 ++++++------- translations/ko/plugin-handbook.md | 210 ++++++++--------- translations/ko/user-handbook.md | 142 ++++++------ translations/nl/plugin-handbook.md | 210 ++++++++--------- translations/nl/user-handbook.md | 150 ++++++------ translations/no/plugin-handbook.md | 228 +++++++++---------- translations/no/user-handbook.md | 138 ++++++------ translations/pl/plugin-handbook.md | 212 ++++++++--------- translations/pl/user-handbook.md | 138 ++++++------ translations/pt-BR/plugin-handbook.md | 269 +++++++++++----------- translations/pt-BR/user-handbook.md | 138 ++++++------ translations/pt-PT/README.md | 12 +- translations/pt-PT/plugin-handbook.md | 226 +++++++++---------- translations/pt-PT/user-handbook.md | 162 ++++++------- translations/ro/plugin-handbook.md | 210 ++++++++--------- translations/ro/user-handbook.md | 136 +++++------ translations/ru/README.md | 10 +- translations/ru/plugin-handbook.md | 280 +++++++++++------------ translations/ru/user-handbook.md | 170 +++++++------- translations/sr/plugin-handbook.md | 210 ++++++++--------- translations/sr/user-handbook.md | 138 ++++++------ translations/sv-SE/README.md | 12 +- translations/sv-SE/plugin-handbook.md | 270 +++++++++++----------- translations/sv-SE/user-handbook.md | 150 ++++++------ translations/tr/README.md | 2 +- translations/tr/plugin-handbook.md | 210 ++++++++--------- translations/tr/user-handbook.md | 150 ++++++------ translations/uk/plugin-handbook.md | 210 ++++++++--------- translations/uk/user-handbook.md | 138 ++++++------ translations/vi/plugin-handbook.md | 210 ++++++++--------- translations/vi/user-handbook.md | 138 ++++++------ translations/zh-Hans/plugin-handbook.md | 210 ++++++++--------- translations/zh-Hans/user-handbook.md | 138 ++++++------ translations/zh-Hant/README.md | 10 +- translations/zh-Hant/plugin-handbook.md | 246 ++++++++++---------- translations/zh-Hant/user-handbook.md | 142 ++++++------ 69 files changed, 5536 insertions(+), 5537 deletions(-) diff --git a/translations/af/plugin-handbook.md b/translations/af/plugin-handbook.md index 1ae48634..3e2a2dfb 100644 --- a/translations/af/plugin-handbook.md +++ b/translations/af/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/af/user-handbook.md b/translations/af/user-handbook.md index c269bd9c..4be5d787 100644 --- a/translations/af/user-handbook.md +++ b/translations/af/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction + * [Introduction](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/ar/plugin-handbook.md b/translations/ar/plugin-handbook.md index 1ae48634..3e2a2dfb 100644 --- a/translations/ar/plugin-handbook.md +++ b/translations/ar/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/ar/user-handbook.md b/translations/ar/user-handbook.md index c269bd9c..4be5d787 100644 --- a/translations/ar/user-handbook.md +++ b/translations/ar/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction + * [Introduction](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/ca/README.md b/translations/ca/README.md index c09f34b5..0eb1b21a 100644 --- a/translations/ca/README.md +++ b/translations/ca/README.md @@ -1,10 +1,10 @@ -# Babel Handbook +# Manual de Babel -This handbook is divided into two parts: +Aquest manual està dividit en dues parts: - * [User Handbook](user-handbook.md) - How to setup/configure Babel and more. - * [Plugin Handbook](plugin-handbook.md) - How to create plugins for Babel. + * [Manual d'usuari](user-handbook.md) - Com configurar Babel i més. + * [Manual d'extensions](plugin-handbook.md) - Com crear extensions per Babel. -> For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter. +> Per a futures actualitzacions, segueix a [@*thejameskyle](https://twitter.com/thejameskyle) en Twitter. -If you are reading a non-english translation of this handbook you may still find english sections that have not yet been translated. If you would like to contribute to one of the translations you must do so through Crowdin. Please read the [contributing guidelines](/CONTRIBUTING.md) for more information. You will find a number of english words that are programming concepts. If these were translated to other languages there would be a lack of consistency and fluency when reading about them. In many cases you will find the literal translation followed by the english term in parenthesis `()`. For example: Abstract Syntax Trees (ASTs). \ No newline at end of file +Si estàs llegint una traducció d'aquest manual, és possible que trobis seccions en anglès que encara no han estat traduïdes. Si desitja contribuir a una de les traduccions haurà de fer-ho a través de Crowdin. Per favor, llegeix les [directrius per contribuir](/CONTRIBUTING.md) per obtenir més informació. Trobaràs diverses paraules en anglès que es corresponen amb conceptes de programació. Si es traduïssin aquestes paraules a altres idiomes hi hauria una falta de consistència i fluïdesa en llegir una altra informació sobre elles. En molts casos trobaràs la traducció literal seguida del terme en anglès entre parèntesi `()`. Per exemple: Arbres de sintaxi abstracta (ASTs). \ No newline at end of file diff --git a/translations/ca/plugin-handbook.md b/translations/ca/plugin-handbook.md index fa89cd90..1a7ce2ea 100644 --- a/translations/ca/plugin-handbook.md +++ b/translations/ca/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definicions](#definitions) - * [Builders](#builders) - * [Validadors](#validators) - * [Convertidors](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Escriure el primer Plugin de Babel](#writing-your-first-babel-plugin) - * [Operacions de transformació](#transformation-operations) - * [Visiting](#visiting) - * [Comprovar si un node és d'un cert tipus](#check-if-a-node-is-a-certain-type) - * [Comprovar si es fa referència un identificador](#check-if-an-identifier-is-referenced) - * [Manipulació](#manipulation) - * [Reemplaçar un node](#replacing-a-node) - * [Reemplaçar un node amb diversos nodes](#replacing-a-node-with-multiple-nodes) - * [Reemplaçar un node amb un string de codi](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Eliminar un node](#removing-a-node) - * [Reemplaçar un pare](#replacing-a-parent) - * [Eliminar un pare](#removing-a-parent) - * [Àmbit d'aplicació](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generar un UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Opcions de plugin](#plugin-options) - * [Building Nodes](#building-nodes) - * [Millors pràctiques](#best-practices) - * [Evitar travessar l'AST tant com sigui possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introducció + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definicions](#toc-definitions) + * [Builders](#toc-builders) + * [Validadors](#toc-validators) + * [Convertidors](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Escriure el primer Plugin de Babel](#toc-writing-your-first-babel-plugin) + * [Operacions de transformació](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Comprovar si un node és d'un cert tipus](#toc-check-if-a-node-is-a-certain-type) + * [Comprovar si es fa referència un identificador](#toc-check-if-an-identifier-is-referenced) + * [Manipulació](#toc-manipulation) + * [Reemplaçar un node](#toc-replacing-a-node) + * [Reemplaçar un node amb diversos nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Reemplaçar un node amb un string de codi](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Eliminar un node](#toc-removing-a-node) + * [Reemplaçar un pare](#toc-replacing-a-parent) + * [Eliminar un pare](#toc-removing-a-parent) + * [Àmbit d'aplicació](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generar un UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Opcions de plugin](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Millors pràctiques](#toc-best-practices) + * [Evitar travessar l'AST tant com sigui possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introducció Babel és un compilador genèric polivalent per a JavaScript. Més que això, és una col·lecció de mòduls que poden ser utilitzats per moltes formes diferents d'anàlisi estàtic. @@ -69,15 +69,15 @@ Babel és un compilador genèric polivalent per a JavaScript. Més que això, é You can use Babel to build many different types of tools that can help you be more productive and write better programs. -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +> ***Per a futures actualitzacions, segueix a [@*thejameskyle](https://twitter.com/thejameskyle) en Twitter.*** * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definicions +### Definicions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validadors +### Validadors The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Convertidors +### Convertidors > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Escriure el primer Plugin de Babel +# Escriure el primer Plugin de Babel Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Operacions de transformació +# Operacions de transformació -## Visiting +## Visiting -### Comprovar si un node és d'un cert tipus +### Comprovar si un node és d'un cert tipus If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Comprovar si es fa referència un identificador +### Comprovar si es fa referència un identificador ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulació +## Manipulació -### Reemplaçar un node +### Reemplaçar un node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Reemplaçar un node amb diversos nodes +### Reemplaçar un node amb diversos nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Reemplaçar un node amb un string de codi +### Reemplaçar un node amb un string de codi ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Eliminar un node +### Eliminar un node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Reemplaçar un pare +### Reemplaçar un pare ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Eliminar un pare +### Eliminar un pare ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Àmbit d'aplicació +## Àmbit d'aplicació -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generar un UID +### Generar un UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Opcions de plugin +# Opcions de plugin If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Millors pràctiques +# Millors pràctiques > I'll be working on this section over the coming weeks. -## Evitar travessar l'AST tant com sigui possible +## Evitar travessar l'AST tant com sigui possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. @@ -1721,4 +1721,4 @@ class Foo { } ``` -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***Per a futures actualitzacions, segueix a [@*thejameskyle](https://twitter.com/thejameskyle) en Twitter.*** \ No newline at end of file diff --git a/translations/ca/user-handbook.md b/translations/ca/user-handbook.md index c269bd9c..7839b1c2 100644 --- a/translations/ca/user-handbook.md +++ b/translations/ca/user-handbook.md @@ -1,63 +1,63 @@ -# Babel User Handbook +# Manual d'usuari de Babel -This document covers everything you ever wanted to know about using [Babel](https://babeljs.io) and related tooling. +Aquest document abasta tot el que sempre ha volgut saber sobre com utilitzar [Babel](https://babeljs.io) i les seves eines relacionades. [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) -This handbook is available in other languages, see the [README](/README.md) for a complete list. - -# Table of Contents - - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction - -Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. - -JavaScript as a language is constantly evolving, with new specs and proposals coming out with new features all the time. Using Babel will allow you to use many of these features years before they are available everywhere. - -Babel does this by compiling down JavaScript code written with the latest standards into a version that will work everywhere today. This process is known as source-to-source compiling, also known as transpiling. - -For example, Babel could transform the new ES2015 arrow function syntax from this: +Aquest manual està disponible en altres idiomes, vegi el [README](/README.md) per a una llista completa. + +# Taula de Continguts + + * [Introducció](#toc-introduction) + * [Iniciant Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Executar Babel CLI dins d'un projecte](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configurant Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configurant Babel (Avançat)](#toc-configuring-babel-advanced) + * [Especificar extensions manualment](#toc-manually-specifying-plugins) + * [Opcions d'extensions](#toc-plugin-options) + * [Personalitzant Babel basat en l'entorn](#toc-customizing-babel-based-on-environment) + * [Fent el seu propi preset](#toc-making-your-own-preset) + * [Babel i altres eines](#toc-babel-and-other-tools) + * [Eines d'anàlisi estàtica](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Estil de codi](#toc-code-style) + * [Documentació](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Editors de text i IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Suport de Babel](#toc-babel-support) + * [Fòrum de Babel](#toc-babel-forum) + * [Xat de Babel](#toc-babel-chat) + * [Problemes en Babel](#toc-babel-issues) + * [Creant un sorprenent report de bugs per Babel](#toc-creating-an-awesome-babel-bug-report) + +# Introducció + +Babel és un compilador multi propòsit per JavaScript. Amb Babel vostè pot utilitzar (i crear) la següent generació de Javascript, així com la següent generació d'eines per Javascript. + +Javascript és un llenguatge en constant evolució, amb noves especificacions i futures propostes arribant amb noves funcionalitats de manera continua. Utilitzant Babel li permetrà fer ús de moltes d'aquestes característiques anys abans de que estiguin disponibles a tot arreu. + +Babel compila el codi escrit en Javascript amb els últims estàndards a una versió que funcionarà a tot arreu. Aquest procés és conegut com a compilació source-to-source, també conegut com transpiling. + +Per exemple, Babel pot transformar la nova funció fletxa d'ES2015 en: ```js const square = n => n * n; ``` -Into the following: +En això: ```js const square = function square(n) { @@ -73,11 +73,11 @@ Further than that, everything in Babel is simply a plugin and anyone can go out Many people do too, the ecosystem that has sprung up around Babel is massive and very diverse. Throughout this handbook I'll be covering both how built-in Babel tools work as well as some useful things from around the community. -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +> ***Per a futures actualitzacions, segueix a [@*thejameskyle](https://twitter.com/thejameskyle) en Twitter.*** * * * -# Setting up Babel +# Iniciant Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Executar Babel CLI dins d'un projecte While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configurant Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configurant Babel (Avançat) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Especificar extensions manualment Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Opcions d'extensions Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Personalitzant Babel basat en l'entorn Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Fent el seu propi preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel i altres eines Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Eines d'anàlisi estàtica Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Estil de codi JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentació Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Editors de text i IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Suport de Babel Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Fòrum de Babel [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Xat de Babel Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Problemes en Babel Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creant un sorprenent report de bugs per Babel Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. @@ -816,4 +816,4 @@ First, try isolating your problem. It's extremely unlikely that every part of yo * * * -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***Per a futures actualitzacions, segueix a [@*thejameskyle](https://twitter.com/thejameskyle) en Twitter.*** \ No newline at end of file diff --git a/translations/cs/plugin-handbook.md b/translations/cs/plugin-handbook.md index 8b534f1e..9d8e59f8 100644 --- a/translations/cs/plugin-handbook.md +++ b/translations/cs/plugin-handbook.md @@ -8,60 +8,60 @@ Tato příručka je k dispozici i v dalších jazycích, úplný seznam naleznet # Obsah - * [Úvod](#introduction) - * [Základy](#basics) - * [AST](#asts) - * [Fáze Babelu](#stages-of-babel) - * [Analýza](#parse) - * [Lexikální analýza](#lexical-analysis) - * [Syntaktická analýza](#syntactic-analysis) - * [Transformace](#transform) - * [Generování](#generate) - * [Průchod](#traversal) - * [Inspektoři](#visitors) - * [Cesty](#paths) - * [Cesty v inspektorech](#paths-in-visitors) - * [Stav](#state) - * [Rozsahy](#scopes) - * [Vazby](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definice](#definitions) - * [Builders](#builders) - * [Validátory](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Psaní prvního pluginu pro Babel](#writing-your-first-babel-plugin) - * [Transformační operace](#transformation-operations) - * [Inspekce](#visiting) - * [Kontrola, zda uzel je určitého typu](#check-if-a-node-is-a-certain-type) - * [Kontrola, zda je identifikátor referencován](#check-if-an-identifier-is-referenced) - * [Manipulace](#manipulation) - * [Nahrazení uzlu](#replacing-a-node) - * [Nahrazení uzlu více uzly](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Vložení uzlu na stejnou úroveň](#inserting-a-sibling-node) - * [Odebrání uzlu](#removing-a-node) - * [Náhrada předka](#replacing-a-parent) - * [Odstranění předka](#removing-a-parent) - * [Rozsah](#scope) - * [Kontrola, zda je lokální proměnná vázána](#checking-if-a-local-variable-is-bound) - * [Generování UID](#generating-a-uid) - * [Strčení deklarace proměnné do nadřazeného rozsahu](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Osvědčené postupy](#best-practices) - * [Vyhněte se co nejvíce procházení AST](#avoid-traversing-the-ast-as-much-as-possible) - * [Slučujte inspektory kdykoli je to možné](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimalizace vnořených inspektorů](#optimizing-nested-visitors) - * [Uvědomte si vnořené struktury](#being-aware-of-nested-structures) - -# Úvod + * [Úvod](#toc-introduction) + * [Základy](#toc-basics) + * [AST](#toc-asts) + * [Fáze Babelu](#toc-stages-of-babel) + * [Analýza](#toc-parse) + * [Lexikální analýza](#toc-lexical-analysis) + * [Syntaktická analýza](#toc-syntactic-analysis) + * [Transformace](#toc-transform) + * [Generování](#toc-generate) + * [Průchod](#toc-traversal) + * [Inspektoři](#toc-visitors) + * [Cesty](#toc-paths) + * [Cesty v inspektorech](#toc-paths-in-visitors) + * [Stav](#toc-state) + * [Rozsahy](#toc-scopes) + * [Vazby](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definice](#toc-definitions) + * [Builders](#toc-builders) + * [Validátory](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Psaní prvního pluginu pro Babel](#toc-writing-your-first-babel-plugin) + * [Transformační operace](#toc-transformation-operations) + * [Inspekce](#toc-visiting) + * [Kontrola, zda uzel je určitého typu](#toc-check-if-a-node-is-a-certain-type) + * [Kontrola, zda je identifikátor referencován](#toc-check-if-an-identifier-is-referenced) + * [Manipulace](#toc-manipulation) + * [Nahrazení uzlu](#toc-replacing-a-node) + * [Nahrazení uzlu více uzly](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Vložení uzlu na stejnou úroveň](#toc-inserting-a-sibling-node) + * [Odebrání uzlu](#toc-removing-a-node) + * [Náhrada předka](#toc-replacing-a-parent) + * [Odstranění předka](#toc-removing-a-parent) + * [Rozsah](#toc-scope) + * [Kontrola, zda je lokální proměnná vázána](#toc-checking-if-a-local-variable-is-bound) + * [Generování UID](#toc-generating-a-uid) + * [Strčení deklarace proměnné do nadřazeného rozsahu](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Osvědčené postupy](#toc-best-practices) + * [Vyhněte se co nejvíce procházení AST](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Slučujte inspektory kdykoli je to možné](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimalizace vnořených inspektorů](#toc-optimizing-nested-visitors) + * [Uvědomte si vnořené struktury](#toc-being-aware-of-nested-structures) + +# Úvod Babel je obecný víceúčelový kompilátor pro JavaScript. Navíc je to kolekce modulů, které mohou být použity pro mnoho různých forem statické analýzy. @@ -73,11 +73,11 @@ Babel můžete použít k vybudování mnoha různých typů nástrojů, které * * * -# Základy +# Základy Babel je kompilátor JavaScriptu, který kompiluje ze zdrojového kódu na zdrojový kód, často nazývaný "transpiler". To znamená, že Babelu předáte kód v JavaScriptu, Babel ho upraví a generuje nový kód zpět. -## AST +## AST Každý z těchto kroků obsahuje vytváření a práci s [Abstraktním syntaktickým stromem](https://en.wikipedia.org/wiki/Abstract_syntax_tree) nebo-li AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Fáze Babelu +## Fáze Babelu The three primary stages of Babel are **parse**, **transform**, **generate**. -### Analýza +### Analýza The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexikální analýza +#### Lexikální analýza Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntaktická analýza +#### Syntaktická analýza Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transformace +### Transformace The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generování +### Generování The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Průchod +## Průchod When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Inspektoři +### Inspektoři When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Cesty +### Cesty An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Cesty v inspektorech +#### Cesty v inspektorech When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### Stav +### Stav State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Rozsahy +### Rozsahy Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Vazby +#### Vazby References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definice +### Definice Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validátory +### Validátory The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Psaní prvního pluginu pro Babel +# Psaní prvního pluginu pro Babel Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformační operace +# Transformační operace -## Inspekce +## Inspekce -### Kontrola, zda uzel je určitého typu +### Kontrola, zda uzel je určitého typu If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Kontrola, zda je identifikátor referencován +### Kontrola, zda je identifikátor referencován ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulace +## Manipulace -### Nahrazení uzlu +### Nahrazení uzlu ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Nahrazení uzlu více uzly +### Nahrazení uzlu více uzly ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Vložení uzlu na stejnou úroveň +### Vložení uzlu na stejnou úroveň ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Odebrání uzlu +### Odebrání uzlu ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Náhrada předka +### Náhrada předka ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Odstranění předka +### Odstranění předka ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Rozsah +## Rozsah -### Kontrola, zda je lokální proměnná vázána +### Kontrola, zda je lokální proměnná vázána ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generování UID +### Generování UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Strčení deklarace proměnné do nadřazeného rozsahu +### Strčení deklarace proměnné do nadřazeného rozsahu Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Osvědčené postupy +# Osvědčené postupy > I'll be working on this section over the coming weeks. -## Vyhněte se co nejvíce procházení AST +## Vyhněte se co nejvíce procházení AST Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Slučujte inspektory kdykoli je to možné +### Slučujte inspektory kdykoli je to možné When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimalizace vnořených inspektorů +## Optimalizace vnořených inspektorů When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Uvědomte si vnořené struktury +## Uvědomte si vnořené struktury Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/cs/user-handbook.md b/translations/cs/user-handbook.md index 9b5bbc5e..7a1539c2 100644 --- a/translations/cs/user-handbook.md +++ b/translations/cs/user-handbook.md @@ -8,42 +8,42 @@ Tato příručka je k dispozici i v dalších jazycích, úplný seznam naleznet # Obsah - * [Úvod](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Úvod + * [Úvod](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Úvod Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/da/plugin-handbook.md b/translations/da/plugin-handbook.md index 1ae48634..3e2a2dfb 100644 --- a/translations/da/plugin-handbook.md +++ b/translations/da/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/da/user-handbook.md b/translations/da/user-handbook.md index c269bd9c..4be5d787 100644 --- a/translations/da/user-handbook.md +++ b/translations/da/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction + * [Introduction](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/de/plugin-handbook.md b/translations/de/plugin-handbook.md index 3f5facad..229c782c 100644 --- a/translations/de/plugin-handbook.md +++ b/translations/de/plugin-handbook.md @@ -8,60 +8,60 @@ Das Handbuch ist in verschiedenen Sprachen verfügbar. Eine vollständige Liste # Table of Contents - * [Einführung](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Einführung + * [Einführung](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Einführung Babel ist ein generischer Compiler für JavaScript. Des weiteren ist es eine Sammlung von Modulen, welche für vielfältige Arten von statischer Analyse benutzt werden können. @@ -73,11 +73,11 @@ Babel kann zur erstellung von verschiedenen Arten von Tools verwedet werden um p * * * -# Basics +# Basics Babel ist ein JavaScript Compiler, genauer ein Source zu Source Compiler, auch "Transpiler" genannt. Das heißt, dass Babel als Eingabe JavsScript Code bekommt, den Code modifiziert und neuen Code als Ausgabe produziert. -## ASTs +## ASTs In jeden dieser Schritte ist das Erstellen oder das Arbeiten mit einem [Abstrakten Syntaxbaum](https://en.wikipedia.org/wiki/Abstract_syntax_tree) oder AST enthalten. @@ -214,15 +214,15 @@ Babel generiert zusätzliche Eigenschaften für jeden Knoten, welche die Positio Die Eigenschaften `start`, `end` und `loc` werden zu jedem Knoten hinzugefügt. -## Stages of Babel +## Stages of Babel Die drei grundsätzlichen Phasen von Babel sind **Parsen(parse)**, **Transformieren(transform)** und **Generieren(generate)**. -### Parse +### Parse Die **parse** Phase erhält Source Code als Eingabe und produziert einen AST als Ausgabe. Die Phase wird in zwei Schritte aufgeteilt: [**Lexikalische Analyse**](https://en.wikipedia.org/wiki/Lexical_analysis) und [**Syntaktische Analyse**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexikalische Analyse nimmt einen Source Code String und wandelt ihn in einen Strom von **Tokens** um. @@ -264,21 +264,21 @@ Jeder `type` hat eine Menge von Eigenschaften welche das Token beschreiben: Analog zu AST Knoten haben Tokens auch eine `start`, `end` und `loc` Eigenschaft. -#### Syntactic Analysis +#### Syntactic Analysis Syntaktische Analyse wandelt einen Strom von Tokens in einen AST um. Diese Phase verwendet die Informationen welche in den Tokens vorhanden ist und wandelt diese in einen AST um, welcher die Struktur des Codes so darstellt welche einfacher bearbeitet werden kann. -### Transform +### Transform Die [Transformations](https://en.wikipedia.org/wiki/Program_transformation)-Phase traversiert einen AST und fügt neue Knoten hinzu, ändert vorhandene Knoten ab oder entfernt Knoten. Dies ist der komplexeste Schritt von Babel oder anderen Compilern. Das ist auch die Phase in welcher Plugins eingesetzt weden und ist somit ein großer Bestandteil dieses Handbuches. Deshalb werden wir diese Phase nicht weiter vertiefen. -### Generate +### Generate Die [Code Generierung](https://en.wikipedia.org/wiki/Code_generation_(compiler)) Phase wandelt den finalen AST wieder in einen String um und erzeugt auch [Source Maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Die Code Generierung ist ziemlich einfach: Der AST wird mit einer Tiefensuche traversiert. Dabei wird eine Zeichenkette generiert, welche den transformierten Code darstellt. -## Traversal +## Traversal Um einen AST zu transformieren muss der Baum rekursiv [durchlaufen](https://en.wikipedia.org/wiki/Tree_traversal) werden. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/de/user-handbook.md b/translations/de/user-handbook.md index ed70bcf1..adb08eb0 100644 --- a/translations/de/user-handbook.md +++ b/translations/de/user-handbook.md @@ -8,42 +8,42 @@ Das Handbuch ist in verschiedenen Sprachen verfügbar. Eine vollständige Liste # Table of Contents - * [Einführung](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Einführung + * [Einführung](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Einführung Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/el/README.md b/translations/el/README.md index c09f34b5..f1b7ebc0 100644 --- a/translations/el/README.md +++ b/translations/el/README.md @@ -1,10 +1,10 @@ -# Babel Handbook +# Εγχειρίδιο Babel -This handbook is divided into two parts: +Αυτό το εγχειρίδιο χωρίζεται σε δύο μέρη: - * [User Handbook](user-handbook.md) - How to setup/configure Babel and more. - * [Plugin Handbook](plugin-handbook.md) - How to create plugins for Babel. + * [Εγχειρίδιο Χρήστη](user-handbook.md) - Πως να ρυθμίσετε το Babel και πολλά άλλα. + * [Εγχειρίδιο Βυσμάτος (Plugin)](plugin-handbook.md) - Πως να δημιουργήσετε βύσματα (plugins) για το Babel. -> For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter. +> Για μελλοντικές ενημερώσεις ακολουθήστε τον [@thejameskyle](https://twitter.com/thejameskyle) στο Twitter. -If you are reading a non-english translation of this handbook you may still find english sections that have not yet been translated. If you would like to contribute to one of the translations you must do so through Crowdin. Please read the [contributing guidelines](/CONTRIBUTING.md) for more information. You will find a number of english words that are programming concepts. If these were translated to other languages there would be a lack of consistency and fluency when reading about them. In many cases you will find the literal translation followed by the english term in parenthesis `()`. For example: Abstract Syntax Trees (ASTs). \ No newline at end of file +Εαν διαβάζετε μια μη-αγγλική μετάφραση του παρόντος εγχειριδίου ίσως να βρείτε τμήματα του κειμένου στα αγγλικά, τα οποία δεν έχουν μεταφραστεί ακόμη. Αν θα θέλατε να συνεισφέρετε σε μια ή περισσότερες μεταφράσεις θα πρέπει να το κάνετε μέσω του Crowdin. Για περισσότερες πληροφορίες παρακαλώ διαβάστε τις [κατευθυντήριες γραμμές συνεισφοράς](/CONTRIBUTING.md). Θα βρείτε έναν αριθμό από αγγλικές λέξεις οι οποίες είναι προγραμματιστικές έννοιες. Αν μεταφραστούν σε άλλες γλώσσες θα υπάρξει ελλειψη συνέπειας και ευχέρειας κατά την ανάγνωση τους. Σε πολλές περιπτώσεις θα βρείτε την κυριολεκτική μετάφραση τους να ακολουθείτε από ένα αγγλικό όρο μέσα σε παρένθεση `()`. Για πάραδειγμα: Αφηρημένη Δενδροειδείς Σύνταξη (ΑΣΔ). \ No newline at end of file diff --git a/translations/el/plugin-handbook.md b/translations/el/plugin-handbook.md index 21009e37..309e259a 100644 --- a/translations/el/plugin-handbook.md +++ b/translations/el/plugin-handbook.md @@ -1,6 +1,6 @@ # Βαβέλ: Εγχειρίδιο για νέους χρήστες -Σε αυτό το κείμενο θα βρείτε όσες πληροφορίες χρειάζεστε για να αρχίσετε να δημιουργείτε. +Σε αυτό το κείμενο θα βρείτε όσες πληροφορίες χρειάζεστε για να αρχίσετε να δημιουργείτε [βύσματα (plugins)](https://babeljs.io) για το <0>Babel. [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) @@ -8,80 +8,80 @@ # ΠΙΝΑΚΑΣ ΠΕΡΙΕΧΟΜΕΝΩΝ - * [Εισαγωγή](#introduction) - * [Βασικά](#basics) - * [Βοήθεια](#asts) - * [Στάδια της Βαβέλ](#stages-of-babel) - * [Ανάλυση](#parse) - * [Λεξικολογική Ανάλυση](#lexical-analysis) - * [Συντακτική Ανάλυση](#syntactic-analysis) - * [Μετατροπή](#transform) - * [Παραγωγή](#generate) - * [Μεταβίβαση](#traversal) - * [Επισκέπτες](#visitors) - * [Καθοδήγηση](#paths) - * [Καθοδήγηση για τους επισκέπτες](#paths-in-visitors) - * [Κατάσταση](#state) - * [Πεδία](#scopes) - * [Σύνδεση](#bindings) - * [Διασύνδεση Προγραμματισμού Εφαρμογών](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Ορισμοί](#definitions) - * [Οικοδόμοι](#builders) - * [Διαδικασίες επικύρωσης](#validators) - * [Μετατροπείς](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Γράφοντας το πρώτο σας Babel Plugin](#writing-your-first-babel-plugin) - * [Λειτουργίες μετατροπής](#transformation-operations) - * [Επισκεψιμότητα](#visiting) - * [Ελέγξτε αν ο κόμβος ανήκει σε κάποιο συγκεκριμένο είδος](#check-if-a-node-is-a-certain-type) - * [Ελέγξτε αν αναφέρεται κάποια άλλη ταυτοποίηση](#check-if-an-identifier-is-referenced) - * [Χειρισμός](#manipulation) - * [Αντικατάσταση κόμβου](#replacing-a-node) - * [Αντικατάσταση κόμβου με πολλούς κόμβους](#replacing-a-node-with-multiple-nodes) - * [Αντικατάσταση κόμβου με πηγαία στοιχειοσειρά](#replacing-a-node-with-a-source-string) - * [Εισαγωγή όμοιου κόμβου](#inserting-a-sibling-node) - * [Αφαίρεση κόμβου](#removing-a-node) - * [Αντικατάσταση κόμβου](#replacing-a-parent) - * [Αφαίρεση γονικής μονάδας](#removing-a-parent) - * [Πλαίσια](#scope) - * [Έλεγχος σύνδεσης τοπικής μεταβλητής ](#checking-if-a-local-variable-is-bound) - * [Κατασκευή αναγνωριστικού χρήστη](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Εισαγωγή - -Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. - -> Static analysis is the process of analyzing code without executing it. (Analysis of code while executing it is known as dynamic analysis). The purpose of static analysis varies greatly. It can be used for linting, compiling, code highlighting, code transformation, optimization, minification, and much more. - -You can use Babel to build many different types of tools that can help you be more productive and write better programs. - -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** + * [Εισαγωγή](#toc-introduction) + * [Βασικά](#toc-basics) + * [ΑΣΔ](#toc-asts) + * [Στάδια του Babel](#toc-stages-of-babel) + * [Ανάλυση](#toc-parse) + * [Λεξικολογική Ανάλυση](#toc-lexical-analysis) + * [Συντακτική Ανάλυση](#toc-syntactic-analysis) + * [Μετατροπή](#toc-transform) + * [Παραγωγή](#toc-generate) + * [Διάσχιση](#toc-traversal) + * [Επισκέπτες](#toc-visitors) + * [Καθοδήγηση](#toc-paths) + * [Καθοδήγηση για τους επισκέπτες](#toc-paths-in-visitors) + * [Κατάσταση](#toc-state) + * [Εμβέλειες](#toc-scopes) + * [Συνδέσεις](#toc-bindings) + * [Διασύνδεση Προγραμματισμού Εφαρμογών](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Ορισμοί](#toc-definitions) + * [Οικοδόμοι](#toc-builders) + * [Διαδικασίες επικύρωσης](#toc-validators) + * [Μετατροπείς](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Γράφοντας το πρώτο σας Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Λειτουργίες μετατροπής](#toc-transformation-operations) + * [Επισκεψιμότητα](#toc-visiting) + * [Ελέγξτε αν ο κόμβος ανήκει σε κάποιο συγκεκριμένο είδος](#toc-check-if-a-node-is-a-certain-type) + * [Ελέγξτε αν αναφέρεται κάποια άλλη ταυτοποίηση](#toc-check-if-an-identifier-is-referenced) + * [Χειρισμός](#toc-manipulation) + * [Αντικατάσταση κόμβου](#toc-replacing-a-node) + * [Αντικατάσταση κόμβου με πολλούς κόμβους](#toc-replacing-a-node-with-multiple-nodes) + * [Αντικατάσταση κόμβου με πηγαία στοιχειοσειρά](#toc-replacing-a-node-with-a-source-string) + * [Εισαγωγή όμοιου κόμβου](#toc-inserting-a-sibling-node) + * [Αφαίρεση κόμβου](#toc-removing-a-node) + * [Αντικατάσταση κόμβου](#toc-replacing-a-parent) + * [Αφαίρεση γονικής μονάδας](#toc-removing-a-parent) + * [Πλαίσια](#toc-scope) + * [Έλεγχος σύνδεσης τοπικής μεταβλητής ](#toc-checking-if-a-local-variable-is-bound) + * [Κατασκευή αναγνωριστικού χρήστη](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Εισαγωγή + +Το Babel είναι ένας γενικός μεταγλωττιστής πολλών χρήσεων για JavaScript. Πιο συγκεκριμένα, είναι μια συλλογή από ενότητες οι οποίες μπορούν να χρησιμοποιηθούν σε διαφορετικές μορφές στατικής ανάλυσης. + +> Στατική ανάλυση είναι η διαδικασία ανάλυσης του κώδικα χωρίς την εκτέλεση του. (Η ανάλυση του κώδικα κατα τη διάρκεια της εκτέλεσης του είναι γνωστή και ως δυναμική ανάλυση). Ο σκοπός της στατικής ανάλυσης ποικίλλει. Μπορεί να χρησιμοποιηθεί για καθάρισμα (linting), μεταγλώττιση, έμφαση (hightlighting), διαμόρφωση, βελτιστοποίηση, σμίκρυνση και πολλά άλλα. + +Μπορείς να χρησιμοποιήσεις το Babel για να κατασκευάσεις πολλούς διαφορετικούς τύπους εργαλείων τα οποία μπορούν να σε βοηθήσουν να γίνεις πιο παραγωγικό και να γράφεις καλύτερα προγράμματα. + +> ***Για μελλοντικές ενημερώσεις, ακολουθήστε [@thejameskyle](https://twitter.com/thejameskyle) στο Twitter.*** * * * -# Βασικά +# Βασικά -Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. +Το Babel είναι ένας μεταγλωττιστής για JavaScript, πιο συγκεκριμένα ένας μεταγλωττιστής από πηγαίο κώδικα σε πηγαίο κωδικα, συχνά αποκαλούμενο «transpiler». Αυτό σημαίνει ότι δίνοντας στο Babel κάποιο κώδικα JavaScript, αυτό τροποποιεί τον κώδικα και παράγει ένα νέο κώδικα. -## Βοήθεια +## ΑΣΔ -Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. +Κάθενα από τα βήματα συμπεριλαμβάνουν την δημιουργία ή χρήση μιας [Αφηρημένης Δενδροειδούς Σύνταξης](https://en.wikipedia.org/wiki/Abstract_syntax_tree) εν συντομία ΑΣΔ. -> Babel uses an AST modified from [ESTree](https://github.com/estree/estree), with the core spec located [here](https://github.com/babel/babel/blob/master/doc/ast/spec.md). +> Το Babel χρησιμοποιεί ένα τροποποιημένο ΑΣΔ [ESTree](https://github.com/estree/estree), ο πυρήνας λεπτομερειών του βρίσκεται [εδώ](https://github.com/babel/babel/blob/master/doc/ast/spec.md). ```js function square(n) { @@ -89,9 +89,9 @@ function square(n) { } ``` -> Check out [AST Explorer](http://astexplorer.net/) to get a better sense of the AST nodes. [Here](http://astexplorer.net/#/Z1exs6BWMq) is a link to it with the example code above pasted in. +> Ρίξτε μια ματιά [AST Explorer](http://astexplorer.net/) για να πάρετε μια καλύτερη αίσθηση των κόμβων ΑΣΔ. [Εδώ](http://astexplorer.net/#/Z1exs6BWMq) βρίσκετε ο σύνδεσμος σε αυτό με παραδείγμα κώδικα το οποίο έχει επικολληθεί παραπάνω. -This same program can be represented as a list like this: +Το ίδιο πρόγραμμα μπορεί να αναπαρασταθεί ως μια λίστα σαν αυτή: ```md - FunctionDeclaration: @@ -116,7 +116,7 @@ This same program can be represented as a list like this: - name: n ``` -Or as a JavaScript Object like this: +Ή ως ένα αντικείμενο JavaScript όπως αυτό: ```js { @@ -150,7 +150,7 @@ Or as a JavaScript Object like this: } ``` -You'll notice that each level of the AST has a similar structure: +Θα παρατηρήσετε ότι κάθε επίπεδο του ΑΣΔ έχει παρόμοια δομή: ```js { @@ -177,11 +177,11 @@ You'll notice that each level of the AST has a similar structure: } ``` -> Note: Some properties have been removed for simplicity. +> Σημείωση: Ορισμένες ιδιότητες έχουν αφαιρεθεί για απλότητα. -Each of these are known as a **Node**. An AST can be made up of a single Node, or hundreds if not thousands of Nodes. Together they are able to describe the syntax of a program that can be used for static analysis. +Κάθενα από αυτά είναι γνωστό ως **Κόμβος**. Ένα ΑΣΔ μπορεί να σχηματιστεί από ένα μόνο Κόμβο ή από εκατοντάδες αν όχι χιλιάδες κόμβους. Μαζί είναι σε θέση να περιγράψουν την σύνταξη ενός προγράμματος, το οποίο μπορεί να χρησιμοποιηθεί για στατική ανάλυση. -Every Node has this interface: +Κάθε Κόμβος έχει αυτή τη διασύνδεση: ```typescript interface Node { @@ -189,9 +189,9 @@ interface Node { } ``` -The `type` field is a string representing the type of Node the object is (ie. `"FunctionDeclaration"`, `"Identifier"`, or `"BinaryExpression"`). Each type of Node defines an additional set of properties that describe that particular node type. +To πέδιο `type` είναι τύπου string και αντιπροσωπεύει τον τύπο του κόμβου, δηλαδή `"ΔήλωσηΣυνάρτησης"`, `"διακριτικό"`, ή `"ΔιαδικήΈκφραση"`. Κάθε τύπος Κόμβου ορίζει ένα πρόσθετο σύνολο από ιδιότητες, οι οποίες περιγράφουν το συγκεκριμένο τύπο κόμβου. -There are additional properties on every Node that Babel generates which describe the position of the Node in the original source code. +Υπάρχουν πρόσθετες ιδιότητες για κάθε Κόμβο τις οποίες το Babel παράγει και οι οποίες περιγράφουν την θέση του Κόμβου στον αρχικό πηγαίο κώδικα. ```js { @@ -212,21 +212,21 @@ There are additional properties on every Node that Babel generates which describ } ``` -These properties `start`, `end`, `loc`, appear in every single Node. +Αυτές οι ιδιότητες `start`, `end`, `loc`, εμφανίζονται σε κάθε Κόμβο. -## Στάδια της Βαβέλ +## Στάδια του Βαβέλ -The three primary stages of Babel are **parse**, **transform**, **generate**. +Τα τρια αρχικά στάδια του Babel είναι **ανάλυση**, **μετατροπή**, **παραγωγή**. -### Ανάλυση +### Ανάλυση -The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). +Το στάδιο **ανάλυση**, λαμβάνει τον κώδικα και εξάγει ένα ΑΣΔ. Υπάρχουν 2 φάσεις της ανάλυσης στο Babel: [**Λεξικολογική Ανάλύση**](https://en.wikipedia.org/wiki/Lexical_analysis) και [**Συντακτική Ανάλυση**](https://en.wikipedia.org/wiki/Parsing). -#### Λεξικολογική Ανάλυση +#### Λεξικολογική Ανάλυση -Lexical Analysis will take a string of code and turn it into a stream of **tokens**. +Η λεξικολογική ανάλυση θα λάβει μια συμβολοσειρά κώδικα (string) και θα την μετατρέψει σε ένα ρεύμα **μαρκών**. -You can think of tokens as a flat array of language syntax pieces. +Μπορείτε να σκεφτείτε τις μάρκες ως μια επίπεδη σειρά από συντακτικά γλωσσικά κομμάτια. ```js n * n; @@ -241,7 +241,7 @@ n * n; ] ``` -Each of the `type`s here have a set of properties describing the token: +Κάθε ένας από τους `τύπους` έχει ένα σύνολογ από ιδιότητες, οι οποίες περιγράφουν την κάθε μάρκα: ```js { @@ -262,27 +262,27 @@ Each of the `type`s here have a set of properties describing the token: } ``` -Like AST nodes they also have a `start`, `end`, and `loc`. +Επίσης οι κόμβοι ΑΣΔ έχουν `start`, `end`, και `loc`. -#### Συντακτική Ανάλυση +#### Συντακτική Ανάλυση -Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. +Η συντακτική ανάλυση θα πάρει ένα ρεύμα από μάρκες και θα τις μετατρέψει σε μια αναπαράσταση ενός ΑΣΔ. Χρησιμοποιώντας τις πληροφορίες από τις μάρκες, αυτή η φάση θα τις μορφοποιησεί σε ένα ΑΣΔ το οποίο αναπαρηστά την δομή του κώδικα με τέτοιο τρόπο ώστε να γίνεται ευκολότερη η διαδικασία εργασίας με αυτό. -### Μετατροπή +### Μετατροπή -The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. +Το στάδιο [μετατροπή](https://en.wikipedia.org/wiki/Program_transformation) λαμβάνει ένα ΑΣΔ και διεισδύει μέσω αυτού στην προσθήκη, ενημέρωση και αφαίρεση κόμβων κατα μήκος της διείσδυσης. Μακράν είναι το πιο περίπλοκο μέρος του Babel ή οποιοδήποτε μεταγλωττιστή. Αυτό είναι το σημείο όπου τα βύσματα (plugins) λειτουργούν και αυτό θα είναι το μεγαλύτερο θέμα που θα ασχοληθούμε σε αυτό το εγχειρίδιο. Για αυτό το λόγο δεν μπορούμε να εμβαθύνουμε αυτή τη στιγμή. -### Παραγωγή +### Παραγωγή -The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). +Το στάδιο [παραγωγής κώδικα](https://en.wikipedia.org/wiki/Code_generation_(compiler)) λαμβάνει το τελικό ΑΣΔ και το μετατρέπει σε μια συμβολοσειρά κώδικα και δημιουργεί και [χάρτες προέλευσης](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). -Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. +Η παραγωγή του κώδικα είναι πολύ απλή: η διεισδυση του ΑΣΔ γίνεται με τον αλγόριθμο "βάθος πρώτα" (depth-first) χτίζοντας μια συμβολοσειρά η οποία αναπαρειστά τον μετασχηματισμένο κώδικα. -## Μεταβίβαση +## Διάσχιση -When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. +Όταν θελεις να μετασχηματίσετε ένα ΑΣΔ πρέπει να [διασχίσεις το δέντρο](https://en.wikipedia.org/wiki/Tree_traversal) αναδρομικά. -Say we have the type `FunctionDeclaration`. It has a few properties: `id`, `params`, and `body`. Each of them have nested nodes. +Ας υποθέσουμε ότι έχουμε τον τύπο `ΔήλωσηΣυνάρτησης`. Έχει μερικές ιδιότητες `διακριτικό`. `παράμετροι`, και `σώμα`. Κάθενα από αυτά έχει εμφωλευμένους κόμβους. ```js { @@ -316,13 +316,13 @@ Say we have the type `FunctionDeclaration`. It has a few properties: `id`, `para } ``` -So we start at the `FunctionDeclaration` and we know its internal properties so we visit each of them and their children in order. +Έτσι ξεκινάμε από την `ΔήλωσηΣυνάρτησης` και γνωρίζουμε τις εσωτερικές ιδιότητες ώστε να επισκευτούμε σε σειρά κάθε μια από αυτές και τα παιδιά τους. -Next we go to `id` which is an `Identifier`. `Identifier`s don't have any child node properties so we move on. +Επείτα πάμε στο `διακριτικό` το οποίο είναι ένα απλό `διακριτικό`. Τα `διακριτικα` δεν έχουν ιδιότητες παιδιών κόμβών, οπότε μπορούμε να προχωρήσουμε. -After that is `params` which is an array of nodes so we visit each of them. In this case it's a single node which is also an `Identifier` so we move on. +Μετέπειτα αυτού έχουμε τις `παραμέτρους` οι οποίες είναι μια σειρά από κόμβους τους οποίους επισκεπτόμαστε. -Then we hit `body` which is a `BlockStatement` with a property `body` that is an array of Nodes so we go to each of them. +Μετά βρίσκουμε το `σώμα` το οποίο είναι ένα `ΚομμάτιΔήλωσης` με την ιδιότητα `σώμα` η οποία είναι μια σειρά από κόμβους έτσι πηγαίνουμε σε καθένα από αυτούς. The only item here is a `ReturnStatement` node which has an `argument`, we go to the `argument` and find a `BinaryExpression`. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Επισκέπτες +### Επισκέπτες When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Καθοδήγηση +### Καθοδήγηση An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Καθοδήγηση για τους επισκέπτες +#### Καθοδήγηση για τους επισκέπτες When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### Κατάσταση +### Κατάσταση State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Πεδία +### Εμβέλειες Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Σύνδεση +#### Συνδέσεις References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# Διασύνδεση Προγραμματισμού Εφαρμογών +# Διασύνδεση Προγραμματισμού Εφαρμογών Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Ορισμοί +### Ορισμοί Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Οικοδόμοι +### Οικοδόμοι You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Διαδικασίες επικύρωσης +### Διαδικασίες επικύρωσης The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Μετατροπείς +### Μετατροπείς > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Γράφοντας το πρώτο σας Babel Plugin +# Γράφοντας το πρώτο σας Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Λειτουργίες μετατροπής +# Λειτουργίες μετατροπής -## Επισκεψιμότητα +## Επισκεψιμότητα -### Ελέγξτε αν ο κόμβος ανήκει σε κάποιο συγκεκριμένο είδος +### Ελέγξτε αν ο κόμβος ανήκει σε κάποιο συγκεκριμένο είδος If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Ελέγξτε αν αναφέρεται κάποια άλλη ταυτοποίηση +### Ελέγξτε αν αναφέρεται κάποια άλλη ταυτοποίηση ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Χειρισμός +## Χειρισμός -### Αντικατάσταση κόμβου +### Αντικατάσταση κόμβου ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Αντικατάσταση κόμβου με πολλούς κόμβους +### Αντικατάσταση κόμβου με πολλούς κόμβους ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Αντικατάσταση κόμβου με πηγαία στοιχειοσειρά +### Αντικατάσταση κόμβου με πηγαία στοιχειοσειρά ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Εισαγωγή όμοιου κόμβου +### Εισαγωγή όμοιου κόμβου ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Αφαίρεση κόμβου +### Αφαίρεση κόμβου ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Αντικατάσταση κόμβου +### Αντικατάσταση κόμβου ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Αφαίρεση γονικής μονάδας +### Αφαίρεση γονικής μονάδας ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Πλαίσια +## Πλαίσια -### Έλεγχος σύνδεσης τοπικής μεταβλητής +### Έλεγχος σύνδεσης τοπικής μεταβλητής ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Κατασκευή αναγνωριστικού χρήστη +### Κατασκευή αναγνωριστικού χρήστη This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. @@ -1721,4 +1721,4 @@ class Foo { } ``` -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***Για μελλοντικές ενημερώσεις ακολουθήστε τον [@thejameskyle](https://twitter.com/thejameskyle) στο Twitter.*** \ No newline at end of file diff --git a/translations/el/user-handbook.md b/translations/el/user-handbook.md index d80420c4..6531ae38 100644 --- a/translations/el/user-handbook.md +++ b/translations/el/user-handbook.md @@ -1,6 +1,6 @@ -# Babel User Handbook +# Εγχειρίδιο Χρήσης Babel -This document covers everything you ever wanted to know about using [Babel](https://babeljs.io) and related tooling. +Αυτό το κέιμενο καλύπτει οτι θα ήθελε να μάθει κάποιος σχετικά με την χρήση του [Babel](https://babeljs.io) και τα σχετικά εργαλεία. [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) @@ -8,56 +8,56 @@ This document covers everything you ever wanted to know about using [Babel](http # ΠΙΝΑΚΑΣ ΠΕΡΙΕΧΟΜΕΝΩΝ - * [Εισαγωγή](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Εισαγωγή - -Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. - -JavaScript as a language is constantly evolving, with new specs and proposals coming out with new features all the time. Using Babel will allow you to use many of these features years before they are available everywhere. - -Babel does this by compiling down JavaScript code written with the latest standards into a version that will work everywhere today. This process is known as source-to-source compiling, also known as transpiling. - -For example, Babel could transform the new ES2015 arrow function syntax from this: + * [Εισαγωγή](#toc-introduction) + * [Ρύθμιση του Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Λειτουργία του Babel CLI μέσα από ένα έργο](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Ρυθμίζοντας το Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Εκτέλεση του παραγώμενου κώδικα απο το Babel](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Ρυθμίζοντας το Babel (για προχωρημένους)](#toc-configuring-babel-advanced) + * [Χειροκίνητος καθορισμός βυσμάτων (plugins)](#toc-manually-specifying-plugins) + * [Επιλογές βυσμάτων (plugins)](#toc-plugin-options) + * [Ρυθμίζοντας το Babel βασιζόμενος στο περιβάλλον](#toc-customizing-babel-based-on-environment) + * [Φτιάχνοντας τη δική σου προεπιλογή](#toc-making-your-own-preset) + * [Babel και άλλα εργαλεία](#toc-babel-and-other-tools) + * [Εργαλεία στατικής ανάλυσης](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Στυλ κώδικα](#toc-code-style) + * [Τεκμηρίωση](#toc-documentation) + * [Πλαισια (Frameworks)](#toc-frameworks) + * [React](#toc-react) + * [Κειμενογράφοι και IDEs](#toc-text-editors-and-ides) + * [Αποσφαλμάτωση του Babel](#toc-debugging-babel) + * [Υποστήριξη του Babel](#toc-babel-support) + * [Φόρουμ του Babel](#toc-babel-forum) + * [Χώρος Συνομιλίας Babel](#toc-babel-chat) + * [Προβλήματα με το Babel](#toc-babel-issues) + * [Δημιουργούντας μια καταπληκτική αναφορά σφάλματος για το Babel](#toc-creating-an-awesome-babel-bug-report) + +# Εισαγωγή + +Το Babel είναι ένας γενικός μεταγλωττιστής πολλών χρήσεων για JavaScript. Χρησιμοποιώντας το Babel μπορείς να χρησιμοποιήσεις (και να δημιουργήσεις) την επόμενη γενιά JavaScript καθώς επίσης και την επόμενη γενιά εργαλείων για JavaScript. + +Η JavaScript ως γλώσσα εξελίσσεται συνεχώς με νέα χαρακτηριστικά καθώς επισης και προτάσεις χαρακτηριστικών. Χρησιμοποιώντας το Babel θα έχεις την δυνατότητα να χρησιμοποιήσεις πολλά από τα χαρακτηριστικά πριν την καθολική διάθεση τους. + +Το Babel το επιτυγχάνει αυτό με την μετάφραση σε κώδικα JavaScript χρησιμοποιώντας τα τελευταία πρότυπα σε μια έκδοση η οποία θα δουλέψει παντού σήμερα. Αυτή η διαδικασία είναι γνωστή ως μεταγλώττιση από πηγαίο κώδικα σε πηγαιό κώδικα, γνωστή και ως transpiling. + +Για παράδειγμα, το Babel θα μπορούσε να μετατρέψει την νέα ES2015 συνάρτηση βέλους (arrow function) από αυτή τη μορφή: ```js const square = n => n * n; ``` -Into the following: +στην παρακάτων: ```js const square = function square(n) { @@ -65,7 +65,7 @@ const square = function square(n) { }; ``` -However, Babel can do much more than this as Babel has support for syntax extensions such as the JSX syntax for React and Flow syntax support for static type checking. +Ωστόσω, το Babel μπορεί να κάνει πολλά περισσότερα από αυτό, αφού το Babel υποστηρίζει την σύνταξη επεκτάσεων (extensions) όπως η σύνταξη JSX που χρησιμοποιηεί το React για τον έλεγχο στατικών τύπων. Further than that, everything in Babel is simply a plugin and anyone can go out and create their own plugins using the full power of Babel to do whatever they want. @@ -73,11 +73,11 @@ Further than that, everything in Babel is simply a plugin and anyone can go out Many people do too, the ecosystem that has sprung up around Babel is massive and very diverse. Throughout this handbook I'll be covering both how built-in Babel tools work as well as some useful things from around the community. -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +> ***Για μελλοντικές ενημερώσεις ακολουθήστε τον [@thejameskyle](https://twitter.com/thejameskyle) στο Twitter.*** * * * -# Setting up Babel +# Ρύθμιση του Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Λειτουργία του Babel CLI μέσα από ένα έργο While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Ρυθμίζοντας το Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Εκτέλεση του παραγώμενου κώδικα απο το Babel So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Ρυθμίζοντας το Babel (για προχωρημένους) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Χειροκίνητος καθορισμός βυσμάτων (plugins) Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Επιλογές βυσμάτων (plugins) Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Ρυθμίζοντας το Babel βασιζόμενος στο περιβάλλον Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Φτιάχνοντας τη δική σου προεπιλογή Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel και άλλα εργαλεία Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Εργαλεία στατικής ανάλυσης Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Στυλ κώδικα JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Τεκμηρίωση Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Πλαισια (Frameworks) All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Κειμενογράφοι και IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Υποστήριξη του Babel Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Φόρουμ του Babel [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Χώρος Συνομιλίας Babel Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Προβλήματα με το Babel Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Δημιουργούντας μια καταπληκτική αναφορά σφάλματος για το Babel Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. @@ -816,4 +816,4 @@ First, try isolating your problem. It's extremely unlikely that every part of yo * * * -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***Για μελλοντικές ενημερώσεις ακολουθήστε τον [@thejameskyle](https://twitter.com/thejameskyle) στο Twitter.*** \ No newline at end of file diff --git a/translations/es-ES/README.md b/translations/es-ES/README.md index 528da042..8a9c41bd 100644 --- a/translations/es-ES/README.md +++ b/translations/es-ES/README.md @@ -7,4 +7,4 @@ Este manual está dividido en dos partes: > Para futuras actualizaciones, sigue a [@thejameskyle](https://twitter.com/thejameskyle) en Twitter. -Si estás leyendo una traducción de este manual, es posible que encuentres secciones en inglés que aún no han sido traducidas. Si desea contribuir a una de las traducciones deberá hacerlo a través de Crowdin. Por favor, lee las [directrices para contribuir](/CONTRIBUTING.md) para obtener más información. Encontrarás varias palabras en inglés que se corresponden con conceptos de programación. Si se tradujeran estas palabras a otros idiomas habría una falta de consistencia y fluidez al leer otra información sobre ellas. En muchos casos encontrarás la traducción literal seguida del término en inglés entre paréntesis `()`. Por ejemplo: Árboles de sintaxis abstracta (AST). \ No newline at end of file +Si estás leyendo una traducción de este manual, es posible que encuentres secciones en inglés que aún no han sido traducidas. Si deseas contribuir a una de las traducciones deberás hacerlo a través de Crowdin. Por favor, lee las [directrices para contribuir](/CONTRIBUTING.md) para obtener más información. Encontrarás varias palabras en inglés que se corresponden con conceptos de programación. Si se tradujeran estas palabras a otros idiomas habría una falta de consistencia y fluidez al leer otra información sobre ellas. En muchos casos encontrarás la traducción literal seguida del término en inglés entre paréntesis `()`. Por ejemplo: Árboles de sintaxis abstracta (AST). \ No newline at end of file diff --git a/translations/es-ES/plugin-handbook.md b/translations/es-ES/plugin-handbook.md index 39282199..2dfc621c 100644 --- a/translations/es-ES/plugin-handbook.md +++ b/translations/es-ES/plugin-handbook.md @@ -8,60 +8,60 @@ Este manual está disponible en otros idiomas, mira el archivo [README](/README. # Tabla de contenido - * [Introducción](#introduction) - * [Conceptos básicos](#basics) - * [Árboles de sintaxis abstracta (AST)](#asts) - * [Etapas de Babel](#stages-of-babel) - * [Análisis](#parse) - * [Análisis léxico](#lexical-analysis) - * [Análisis sintáctico](#syntactic-analysis) - * [Transform](#transform) - * [Síntesis](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definiciones](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Escribiendo tu primer plugin para Babel](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introducción + * [Introducción](#toc-introduction) + * [Conceptos básicos](#toc-basics) + * [Árboles de sintaxis abstracta (AST)](#toc-asts) + * [Etapas de Babel](#toc-stages-of-babel) + * [Análisis](#toc-parse) + * [Análisis léxico](#toc-lexical-analysis) + * [Análisis sintáctico](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Síntesis](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definiciones](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Escribiendo tu primer plugin para Babel](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introducción Babel es un compilador multi propósito para Javascript. Más que eso es una colección de módulos que pueden ser usados en diferentes formas de análisis estático. @@ -73,11 +73,11 @@ Babel puede ser usado para construir diferentes tipos de herramientas, las cuale * * * -# Conceptos básicos +# Conceptos básicos Babel es un compilador de JavaScript, específicamente un compilador de fuente a fuente, a menudo llamado "transpiler". Esto significa le entregas a Babel código en JavaScript, Babel lo modifica y devuelve el código nuevo creado en Javascript. -## ASTs +## ASTs Cada uno de estos pasos implican crear o trabajar con un [Árbol de sintaxis abstracta](https://en.wikipedia.org/wiki/Abstract_syntax_tree) ó AST por sus siglas en inglés. @@ -214,15 +214,15 @@ Hay propiedades adicionales en cada nodo que Babel genera para describir la posi Estas propiedades ` start `, `end`, `loc`, aparecen en cada uno de los nodos. -## Etapas de Babel +## Etapas de Babel Las tres etapas principales de Babel son **analizar**, **transformar**, **generar**. -### Analizar +### Analizar La etapa de **análisis**, recibe código a la entrada y entrega un AST a la salida. Hay dos fases de análisis en Babel: [**Análisis léxico**](https://en.wikipedia.org/wiki/Lexical_analysis) y [**Análisis sintáctico**](https://en.wikipedia.org/wiki/Parsing). -#### Análisis léxico +#### Análisis léxico El análisis léxico recibe una cadena de código y lo convierte en una secuencia de **tokens**. @@ -264,21 +264,21 @@ Aquí cada uno de los `tipo`s tienen un conjunto de propiedades que describen el Así como los nodos AST, estos también tienen `start`, `end` y `loc`. -#### Análisis sintáctico +#### Análisis sintáctico El análisis sintáctico recibe una secuencia de tokens y lo convierten en una representación de AST. Usando la información de los tokens, esta fase les cambia el formato y los representa en un AST. El cual representa la estructura del código de una manera más sencilla para trabajar. -### Transformar +### Transformar La etapa de [transformación](https://en.wikipedia.org/wiki/Program_transformation) toma un AST y cruza a través de él, agregando, actualizando y quitando nodos a medida que va avanzando. Esta es, por lejos, la parte más compleja de Babel o cualquier otro compilador. Aquí es donde los plugins operan, así que este será el tema pricncipal de este manual. Por ahora no lo analizaremos en detalle. -### Generar +### Generar La etapa de [generación de código](https://en.wikipedia.org/wiki/Code_generation_(compiler)) toma el AST final y lo convierte nuevamente en una cadena de código, creando además [mapas de fuente](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Generar el código es bastante simple: se recorre a través del AST, empezando en lo más profundo, construyendo una cadena que representa el código transformado. -## Recorrido +## Recorrido Cuando se desea transformar un AST es necesario [recorrer el árbol](https://en.wikipedia.org/wiki/Tree_traversal) de manera recursiva. @@ -330,11 +330,11 @@ La `BinaryExpression` tiene tres propiedades ` operator`, `left` y `right`. El o Este proceso de recorrido, en Babel, pasa a lo largo de la etapa de transformación. -### Visitantes +### Visitantes -When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). +Cuando decimos que "vamos" a un nodo, lo que realmente queremos decir es que los estamos **visitando**. Se utiliza éste término porque existe el concepto de [**visitante**](https://en.wikipedia.org/wiki/Visitor_pattern) (visitor). -Visitors are a pattern used in AST traversal across languages. Simply put they are an object with methods defined for accepting particular node types in a tree. That's a bit abstract so let's look at an example. +Visitors are a pattern used in AST traversal across languages. Básicamente son objetos, con métodos definidos para aceptar ciertos tipos de nodos en un árbol. Esto es un poco abstracto, veamos un ejemplo. ```js const MyVisitor = { @@ -344,7 +344,7 @@ const MyVisitor = { }; ``` -> **Note:** `Identifier() { ... }` is shorthand for `Identifier: { enter() { ... } }`. +> **Nota:**`Identifier() { ... }` es la abreviatura de `Identifier: { enter() { ... } }`. This is a basic visitor that when used during a traversal will call the `Identifier()` method for every `Identifier` in the tree. @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definiciones +### Definiciones Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Escribiendo tu primer plugin para Babel +# Escribiendo tu primer plugin para Babel Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/es-ES/user-handbook.md b/translations/es-ES/user-handbook.md index e62821e3..95abaf17 100644 --- a/translations/es-ES/user-handbook.md +++ b/translations/es-ES/user-handbook.md @@ -1,53 +1,53 @@ # Manual de usuario de Babel -Este documento abarca todo lo que siempre quizo saber sobre como usar [Babel](https://babeljs.io) y herramientas relacionadas. +Este documento abarca todo lo que siempre quizo saber sobre como usar [Babel](https://babeljs.io) y sus herramientas relacionadas. [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) -Este manuel está disponible en otros idiomas, vea el [README](/README.md) para una lista completa. +Este manual está disponible en otros idiomas, revise el [README](/README.md) para que pueda visualizar la lista completa. # Tabla de Contenidos - * [Introducción](#introduction) - * [Iniciando Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Ejecutar Babel CLI dentro de un proyecto](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuración de Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Ejecutar código generado en Babel](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuración de Babel (Avanzado)](#configuring-babel-advanced) - * [Especificar extensiones manualmente](#manually-specifying-plugins) - * [Opciones de extensiones](#plugin-options) - * [Personalizar Babel basado en el entorno](#customizing-babel-based-on-environment) - * [Haciendo su propio preset](#making-your-own-preset) - * [Babel y otras herramientas](#babel-and-other-tools) - * [Herramientas de análisis estático](#static-analysis-tools) - * [Linting](#linting) - * [Estilo de código](#code-style) - * [Documentación](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Editores de texto e IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Soporte de Babel](#babel-support) - * [Foro de Babel](#babel-forum) - * [Chat de Babel](#babel-chat) - * [Problemas en Babel](#babel-issues) - * [Crear un sorprendente reporte de fallos de Babel](#creating-an-awesome-babel-bug-report) - -# Introducción + * [Introducción](#toc-introduction) + * [Iniciando Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Ejecutar Babel CLI dentro de un proyecto](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuración de Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Ejecutar código generado en Babel](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuración de Babel (Avanzado)](#toc-configuring-babel-advanced) + * [Especificar extensiones manualmente](#toc-manually-specifying-plugins) + * [Opciones de extensiones](#toc-plugin-options) + * [Personalizar Babel basado en el entorno](#toc-customizing-babel-based-on-environment) + * [Haciendo su propio preset](#toc-making-your-own-preset) + * [Babel y otras herramientas](#toc-babel-and-other-tools) + * [Herramientas de análisis estático](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Estilo de código](#toc-code-style) + * [Documentación](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Editores de texto e IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Soporte de Babel](#toc-babel-support) + * [Foro de Babel](#toc-babel-forum) + * [Chat de Babel](#toc-babel-chat) + * [Problemas en Babel](#toc-babel-issues) + * [Crear un sorprendente reporte de fallos de Babel](#toc-creating-an-awesome-babel-bug-report) + +# Introducción Babel es un compilador multi propósito para Java Script. Al usar Babel usted puede usar (y crear) la siguiente generación de JavaScript, así como la siguiente generación de herramientas para JavaScript. -JavaScript es un lenguaje en constante evolución, con nuevas especificaciones y propuestas viniendo y nuevas funcionalidades todo el tiempo. Usar Babel le permitirá usar muchas de estás características años anted de que estén disponibles en todos lados. +JavaScript es un lenguaje en constante evolución, con nuevas especificaciones, propuestas en camino y nuevas funcionalidades todo el tiempo. Usar Babel le permitirá usar muchas de estás características años antes de que estén disponibles en todos lados. Babel hace esto al compilar código en JavaScript escrito con los últimos estándares a una versión que funcionará en todos lados hoy. Este proceso es conocido como compilación source-to-source, también conocido como transpiling. @@ -65,9 +65,9 @@ const square = function square(n) { }; ``` -Sin embargo, Babel puede hacer mucho mas que esto por que Babel tiene soporte para extensiones de sintaxis como JSX para React y soporte para la sintaxis de Flow para validación de tipado estático. +Sin embargo, Babel puede hacer mucho más que esto porque Babel tiene soporte para extensiones de sintaxis como JSX para React y soporte para la sintaxis de Flow para validación de tipado estático. -Más allá de eso, todo en Babel es simplemente una extensión y cualquiera puede ir y crear sus propias extensiones usando todo el poder de Babel para hacer cualquier cosa que se deseé. +Más allá de eso, todo en Babel es simplemente una extensión y cualquiera puede crear sus propias extensiones usando todo el poder de Babel para hacer cualquier cosa que se deseé. *Aún más allá* que eso, Babel está conformado por un numero de módulos clave que cualquiera puede usar para construir la siguiente generación de herramientas para JavaScript. @@ -77,7 +77,7 @@ Muchas personas hacen eso también, el ecosistema que se ha formado alrededor de * * * -# Iniciando Babel +# Iniciando Babel Debido a que la comunidad de JavaScript no tiene una sola herramienta, framework o plataforma etc., Babel tiene integraciones oficiales con las herramientas de trabajo más comunes. Todo desde Gulp hasta Browserify, desde Ember a Meteor, no importa como su configuración se vea, existe probablemente una integración oficial. @@ -85,7 +85,7 @@ Para los propósitos de este manual, solo se van a cubrir las partes incorporada > **Nota:** Esta guía usará referencias recurrentes a herramientas de la linea de comandos como `node` y `npm`. Antes de continuar usted debe sentirse cómodo con estas tecnologías. -## `babel-cli` +## `babel-cli` Babel CLI es una forma simple de compilar archivos con Babel desde la linea de comandos. @@ -117,9 +117,9 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Ejecutar Babel CLI dentro de un proyecto +### Ejecutar Babel CLI dentro de un proyecto -Si buen usted *puede* instalar Babel CLI globalmente en su máquina, es mucho mejor instalarlo **localmente** en cada proyecto. +Si bien usted *puede* instalar Babel CLI globalmente en su máquina, es mucho mejor instalarlo **localmente** en cada proyecto. Hay dos principales razones para esto. @@ -132,9 +132,9 @@ Podemos instalar Babel CLI localmente ejecutando: $ npm install --save-dev babel-cli ``` -> **Nota:** Debido a que es generalmente una mala idea correr Babel globalmente, usted podría desear desinstalar la copia global ejecutando `pm uninstall --global babel-cli`. +> **Nota:** Debido a que es generalmente una mala idea correr Babel globalmente, usted podría desear desinstalar la copia global ejecutando `npm uninstall --global babel-cli`. -Después de terminarse de instalar, su archivo `package.json` debería lucir como esto: +Después de terminarse de instalar, su archivo `package.json` debería verse algo así: ```json { @@ -146,7 +146,7 @@ Después de terminarse de instalar, su archivo `package.json` debería lucir com } ``` -Ahora en vez de ejecutar Babel directamente desde la línea de comandos vamos a escribir nuestros comando en **npm scripts** los cuales usarán nuestra versión loca. +Ahora, en vez de ejecutar Babel directamente desde la línea de comandos, vamos a escribir nuestros comandos en **npm scripts** los cuales usarán nuestra versión local. Simplemente añada el campo `"scripts"` a su paquete `package.json` y ponga el comando de babel dentro como `build`. @@ -163,15 +163,15 @@ Simplemente añada el campo `"scripts"` a su paquete `package.json` y ponga el c } ``` -Now from our terminal we can run: +Ahora desde nuestro terminal podemos correr lo siguiente: ```js -npm run build +$ npm run build ``` -This will run Babel the same way as before, only now we are using a local copy. +Esto ejecutará Babel igual que antes, sólo que ahora estamos usando una copia local. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuración de Babel +# Configuración de Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Ejecutar código generado en Babel +# Ejecutar código generado en Babel So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuración de Babel (Avanzado) +# Configuración de Babel (Avanzado) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Especificar extensiones manualmente +## Especificar extensiones manualmente Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Opciones de extensiones +## Opciones de extensiones Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Personalizar Babel basado en el entorno +## Personalizar Babel basado en el entorno Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Haciendo su propio preset +## Haciendo su propio preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel y otras herramientas +# Babel y otras herramientas Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Herramientas de análisis estático +## Herramientas de análisis estático Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Estilo de código +### Estilo de código JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentación +### Documentación Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Editores de texto e IDEs +## Editores de texto e IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Soporte de Babel +# Soporte de Babel Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Foro de Babel +## Foro de Babel [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Chat de Babel +## Chat de Babel Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Problemas en Babel +## Problemas en Babel Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Crear un sorprendente reporte de fallos de Babel +### Crear un sorprendente reporte de fallos de Babel Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/fi/plugin-handbook.md b/translations/fi/plugin-handbook.md index 1ae48634..3e2a2dfb 100644 --- a/translations/fi/plugin-handbook.md +++ b/translations/fi/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/fi/user-handbook.md b/translations/fi/user-handbook.md index c269bd9c..4be5d787 100644 --- a/translations/fi/user-handbook.md +++ b/translations/fi/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction + * [Introduction](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/fr/plugin-handbook.md b/translations/fr/plugin-handbook.md index 0caea2a3..21527174 100644 --- a/translations/fr/plugin-handbook.md +++ b/translations/fr/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Sommaire - * [Introduction](#introduction) - * [Notions de base](#basics) - * [ASTs](#asts) - * [Les étapes de Babel](#stages-of-babel) - * [Parse](#parse) - * [Analyse lexicale](#lexical-analysis) - * [Analyse syntaxique](#syntactic-analysis) - * [Transformer](#transform) - * [Générer](#generate) - * [Traversal](#traversal) - * [Visiteurs](#visitors) - * [Chemins d'accès](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [Etat](#state) - * [Scopes](#scopes) - * [Liaisons](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Définitions](#definitions) - * [Constructeurs](#builders) - * [Validateurs](#validators) - * [Convertisseurs](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Votre premier plugin Babel](#writing-your-first-babel-plugin) - * [Opérations de transformations](#transformation-operations) - * [Visite](#visiting) - * [Vérifier si un nœud est un certain type](#check-if-a-node-is-a-certain-type) - * [Vérifie si un identificateur est référencié](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Remplacer un nœud](#replacing-a-node) - * [Remplacer un nœud avec plusieurs nœuds](#replacing-a-node-with-multiple-nodes) - * [Remplacer un nœud avec une chaîne de caractères](#replacing-a-node-with-a-source-string) - * [Insertion d'un nœud enfant](#inserting-a-sibling-node) - * [Suppression d'un nœud](#removing-a-node) - * [Remplacement d'un parent](#replacing-a-parent) - * [Suppression d'un parent](#removing-a-parent) - * [Scope](#scope) - * [Vérifier si une variable locale est liée](#checking-if-a-local-variable-is-bound) - * [Générer un UID](#generating-a-uid) - * [Pousser une déclaration de variable vers un scope parent](#pushing-a-variable-declaration-to-a-parent-scope) - * [Renommer une liaison et ses références](#rename-a-binding-and-its-references) - * [Options du plugin](#plugin-options) - * [Nœuds de création](#building-nodes) - * [Meilleures pratiques](#best-practices) - * [Éviter de traverser l'AST autant que possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Fusionner les visiteurs quand c'est possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimisation des visiteurs imbriqués](#optimizing-nested-visitors) - * [Etre conscient des structures imbriqués](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Notions de base](#toc-basics) + * [ASTs](#toc-asts) + * [Les étapes de Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Analyse lexicale](#toc-lexical-analysis) + * [Analyse syntaxique](#toc-syntactic-analysis) + * [Transformer](#toc-transform) + * [Générer](#toc-generate) + * [Traversal](#toc-traversal) + * [Visiteurs](#toc-visitors) + * [Chemins d'accès](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [Etat](#toc-state) + * [Scopes](#toc-scopes) + * [Liaisons](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Définitions](#toc-definitions) + * [Constructeurs](#toc-builders) + * [Validateurs](#toc-validators) + * [Convertisseurs](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Votre premier plugin Babel](#toc-writing-your-first-babel-plugin) + * [Opérations de transformations](#toc-transformation-operations) + * [Visite](#toc-visiting) + * [Vérifier si un nœud est un certain type](#toc-check-if-a-node-is-a-certain-type) + * [Vérifie si un identificateur est référencié](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Remplacer un nœud](#toc-replacing-a-node) + * [Remplacer un nœud avec plusieurs nœuds](#toc-replacing-a-node-with-multiple-nodes) + * [Remplacer un nœud avec une chaîne de caractères](#toc-replacing-a-node-with-a-source-string) + * [Insertion d'un nœud enfant](#toc-inserting-a-sibling-node) + * [Suppression d'un nœud](#toc-removing-a-node) + * [Remplacement d'un parent](#toc-replacing-a-parent) + * [Suppression d'un parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Vérifier si une variable locale est liée](#toc-checking-if-a-local-variable-is-bound) + * [Générer un UID](#toc-generating-a-uid) + * [Pousser une déclaration de variable vers un scope parent](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Renommer une liaison et ses références](#toc-rename-a-binding-and-its-references) + * [Options du plugin](#toc-plugin-options) + * [Nœuds de création](#toc-building-nodes) + * [Meilleures pratiques](#toc-best-practices) + * [Éviter de traverser l'AST autant que possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Fusionner les visiteurs quand c'est possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimisation des visiteurs imbriqués](#toc-optimizing-nested-visitors) + * [Etre conscient des structures imbriqués](#toc-being-aware-of-nested-structures) + +# Introduction Babel est un compilateur multi-purpose générique pour JavaScript. Plus que cela, c'est une collection de modules qui peuvent être utilisées de nombreuses formes différentes d'analyse statique. @@ -73,11 +73,11 @@ Vous pouvez utiliser Babel pour construire différents types d'outils qui peuven * * * -# Notions de base +# Notions de base Babel est un compilateur JavaScript, plus précisément un compilateur de code source à un autre, souvent appelé un « transpiler ». Cela signifie que vous donnez à Babel du code JavaScript, Babel modifie le code et génère un nouveau code en sortie. -## ASTs +## ASTs Chacune de ces étapes implique la création ou le travaille avec une [Arbre de syntaxe abstraite](https://en.wikipedia.org/wiki/Abstract_syntax_tree) ou AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Les étapes de Babel +## Les étapes de Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Analyse lexicale +#### Analyse lexicale Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Analyse syntaxique +#### Analyse syntaxique Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transformer +### Transformer The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Générer +### Générer The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visiteurs +### Visiteurs When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Chemins d'accès +### Chemins d'accès An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### Etat +### Etat State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Liaisons +#### Liaisons References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Définitions +### Définitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Constructeurs +### Constructeurs You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validateurs +### Validateurs The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Convertisseurs +### Convertisseurs > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Votre premier plugin Babel +# Votre premier plugin Babel Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Opérations de transformations +# Opérations de transformations -## Visite +## Visite -### Vérifier si un nœud est un certain type +### Vérifier si un nœud est un certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Vérifie si un identificateur est référencié +### Vérifie si un identificateur est référencié ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Remplacer un nœud +### Remplacer un nœud ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Remplacer un nœud avec plusieurs nœuds +### Remplacer un nœud avec plusieurs nœuds ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Remplacer un nœud avec une chaîne de caractères +### Remplacer un nœud avec une chaîne de caractères ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Insertion d'un nœud enfant +### Insertion d'un nœud enfant ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Suppression d'un nœud +### Suppression d'un nœud ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Remplacement d'un parent +### Remplacement d'un parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Suppression d'un parent +### Suppression d'un parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Vérifier si une variable locale est liée +### Vérifier si une variable locale est liée ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Générer un UID +### Générer un UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pousser une déclaration de variable vers un scope parent +### Pousser une déclaration de variable vers un scope parent Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Renommer une liaison et ses références +### Renommer une liaison et ses références ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Options du plugin +# Options du plugin If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Nœuds de création +# Nœuds de création When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Meilleures pratiques +# Meilleures pratiques > I'll be working on this section over the coming weeks. -## Éviter de traverser l'AST autant que possible +## Éviter de traverser l'AST autant que possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Fusionner les visiteurs quand c'est possible +### Fusionner les visiteurs quand c'est possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimisation des visiteurs imbriqués +## Optimisation des visiteurs imbriqués When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Etre conscient des structures imbriqués +## Etre conscient des structures imbriqués Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/fr/user-handbook.md b/translations/fr/user-handbook.md index 643ea907..bcba0aa4 100644 --- a/translations/fr/user-handbook.md +++ b/translations/fr/user-handbook.md @@ -8,42 +8,42 @@ Ce manuel est disponible dans d'autres langues, voir le [README](/README.md) pou # Sommaire - * [Introduction](#introduction) - * [Mise en place de Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction + * [Introduction](#toc-introduction) + * [Mise en place de Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduction Babel est un compilateur générique et multi-usage pour JavaScript. L'utilisation de Babel, vous permet d'utiliser (et de créer) la prochaine génération de JavaScript, aussi bien que la prochaine génération des outils JavaScript. @@ -77,7 +77,7 @@ Beaucoup de gens l'ont déjà fait, et l'écosystème qui a surgi autour de Babe * * * -# Mise en place de Babel +# Mise en place de Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/he/plugin-handbook.md b/translations/he/plugin-handbook.md index b87704c6..f04094a4 100644 --- a/translations/he/plugin-handbook.md +++ b/translations/he/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # תוכן העניינים - * [מבוא](#introduction) - * [יסודות](#basics) - * [ASTs](#asts) - * [השלבים של Babel](#stages-of-babel) - * [ניתוח (Parse)](#parse) - * [ניתוח מילולי (Lexical Analysis)](#lexical-analysis) - * [ניתוח תחבירי (Syntactic Analysis)](#syntactic-analysis) - * [שינוי צורה (Transform)](#transform) - * [יצירה](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# מבוא + * [מבוא](#toc-introduction) + * [יסודות](#toc-basics) + * [ASTs](#toc-asts) + * [השלבים של Babel](#toc-stages-of-babel) + * [ניתוח (Parse)](#toc-parse) + * [ניתוח מילולי (Lexical Analysis)](#toc-lexical-analysis) + * [ניתוח תחבירי (Syntactic Analysis)](#toc-syntactic-analysis) + * [שינוי צורה (Transform)](#toc-transform) + * [יצירה](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# מבוא Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# יסודות +# יסודות Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## השלבים של Babel +## השלבים של Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### ניתוח (Parse) +### ניתוח (Parse) The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### ניתוח מילולי (Lexical Analysis) +#### ניתוח מילולי (Lexical Analysis) Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### ניתוח תחבירי (Syntactic Analysis) +#### ניתוח תחבירי (Syntactic Analysis) Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### שינוי צורה (Transform) +### שינוי צורה (Transform) The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### יצירה +### יצירה The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/he/user-handbook.md b/translations/he/user-handbook.md index 950a0e7e..1b2505a3 100644 --- a/translations/he/user-handbook.md +++ b/translations/he/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # תוכן העניינים - * [מבוא](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# מבוא + * [מבוא](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# מבוא Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/hu/plugin-handbook.md b/translations/hu/plugin-handbook.md index 1ae48634..3e2a2dfb 100644 --- a/translations/hu/plugin-handbook.md +++ b/translations/hu/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/hu/user-handbook.md b/translations/hu/user-handbook.md index c269bd9c..4be5d787 100644 --- a/translations/hu/user-handbook.md +++ b/translations/hu/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction + * [Introduction](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/id-ID/plugin-handbook.md b/translations/id-ID/plugin-handbook.md index b03ba121..da0173f9 100644 --- a/translations/id-ID/plugin-handbook.md +++ b/translations/id-ID/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Daftar Isi - * [Pengenalan](#introduction) - * [Dasar](#basics) - * [ASTs](#asts) - * [Status Babel](#stages-of-babel) - * [Penguraian](#parse) - * [Analisis Leksikal](#lexical-analysis) - * [Analisis Sintaktik](#syntactic-analysis) - * [Transformasi](#transform) - * [Pembuatan](#generate) - * [Traversal](#traversal) - * [Pengunjung](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Pengenalan + * [Pengenalan](#toc-introduction) + * [Dasar](#toc-basics) + * [ASTs](#toc-asts) + * [Status Babel](#toc-stages-of-babel) + * [Penguraian](#toc-parse) + * [Analisis Leksikal](#toc-lexical-analysis) + * [Analisis Sintaktik](#toc-syntactic-analysis) + * [Transformasi](#toc-transform) + * [Pembuatan](#toc-generate) + * [Traversal](#toc-traversal) + * [Pengunjung](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Pengenalan Babel adalah compiler JavaScript umum yang multifungsi. Selebihnya, Babel adalah kumpulan modul yang dapat digunakan untuk beberapa bentuk analisis statik. @@ -73,11 +73,11 @@ Anda dapat menggunakan Babel untuk membangun beberapa tipe perkakas yang dapat m * * * -# Dasar +# Dasar Babel adalah compiler JavaScript, yang lebih spesifik sebuah kompiler sumber ke sumber, sering disebut "transpiler". Ini berarti bahwa anda memberi beberapa kode JavaScript kepada Babel, Babel memodifikasi kodenya, dan membuat kode baru dari proses di belakangnya. -## ASTs +## ASTs Setiap langkah meliputi pembuatan atau pengerjaan [Pohon Sintak Abstrak](https://en.wikipedia.org/wiki/Abstract_syntax_tree) atau AST. @@ -214,15 +214,15 @@ Ada properti tambahan pada setiap Node bahwa Babel menghasilkan yang menggambark Properti seperti `mulai`, `akhir`, `loc`, muncul dalam setiap Node tunggal. -## Status Babel +## Status Babel Tiga tahap utama dari Babel adalah **penguraian**, **transformasi**, **pembuatan**. -### Penguraian +### Penguraian Tahap **penguraian**, mengambil kode dan mengembalikan AST. Ada dua fase mengurai di Babel: [**Analisis leksikal**](https://en.wikipedia.org/wiki/Lexical_analysis) dan [**Analisis sintaksis**](https://en.wikipedia.org/wiki/Parsing). -#### Analisis Leksikal +#### Analisis Leksikal Analisis leksikal akan mengambil serangkaian kode dan mengubahnya menjadi aliran **tokens**. @@ -264,21 +264,21 @@ Masing-masing `type` di sini memiliki seperangkat sifat-sifat yang menggambarkan Seperti AST node mereka juga memiliki `start`, `end`, dan `loc`. -#### Analisis Sintaktik +#### Analisis Sintaktik Analisis sintaksis akan mengambil aliran token dan mengubahnya menjadi representasi AST. Menggunakan informasi dalam token, fase ini akan memformat mereka sebagai AST yang mewakili struktur kode dalam cara yang membuatnya lebih mudah untuk bekerja. -### Transformasi +### Transformasi Tahap [transformasi](https://en.wikipedia.org/wiki/Program_transformation) mengambil AST dan melintasi, menambahkan, memperbarui, dan menghapus node dalam prosesnya. Ini adalah bagian paling kompleks dari Babel atau kompiler apapun. Ini adalah tempat plugin beroperasi dan ini akan berupa sebagian besar buku ini. Jadi kita tidak akan menyelam terlalu jauh sekarang. -### Pembuatan +### Pembuatan Tahap [pembuatan kode](https://en.wikipedia.org/wiki/Code_generation_(compiler)) mengambil AST akhir dan mengubah kembali menjadi serangkaian kode, juga menciptakan [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Pembuatan kode ini cukup sederhana: Anda melintasi melalui AST pada kedalaman pertama, membangun sebuah string yang mewakili kode yang sudah ditransormasi. -## Traversal +## Traversal Bila Anda ingin mengubah AST Anda harus [melintasi pohon](https://en.wikipedia.org/wiki/Tree_traversal) secara rekursif. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Pengunjung +### Pengunjung Ketika kita berbicara tentang "pergi" ke sebuah node, kita benar-benar mengartikan untuk **mengunjungi** mereka. Kita menggunakan istilah itu alasannya karena ada konsep [**pengunjung**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ Sama halnya dengan metode yang berhubungan dengan menambahkan, update, memindahk Dalam artinya, paths adalah sebuah representasi **reaktif** dari posisi node di pohon dan segala macam informasi tentang node. Setiap kali Anda memanggil metode yang memodifikasi pohon, informasi ini diperbarui. Babel mengelola semua ini bagi anda untuk membuat bekerja dengan node mudah dan semakin stateless. -#### Paths in Visitors +#### Paths in Visitors Bila Anda memiliki pengunjung yang memiliki metode`Identifier()`, Anda benar-benar mengunjungi path bukan node. Dengan cara ini Anda sebagian besar bekerja dengan perwakilan reaktif dari sebuah node bukan node itu sendiri. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Tentu saja, ini adalah contoh yang dibuat-buat, tapi ini menunjukkan bagaimana untuk menghilangkan state global dari pengunjung anda. -### Scopes +### Scopes Selanjutnya mari kita belajar konsep [**cakupan**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript memiliki [cakupan leksikal](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), yang merupakan struktur pohon di mana blok dapat membuat cakupan baru. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings Semua referensi adalah milik cakupan tertentu; hubungan ini dikenal sebagai **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon adalah pengurai Babel. Dimulai sebagai sebuah fork dari Acorn, dia cepat, mudah digunakan, memiliki arsitektur berbasis plugin untuk non-standar fitur (serta standar masa depan). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators Definisi `BinaryExpression` juga mencakup informasi tentang `bidang` sebuah node dan bagaimana melakukan validasi. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do Mungkin juga akan tergoda untuk memanggil `path.traverse` ketika mencari jenis node tertentu. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors Ketika Anda pengunjung bertingkat, hal itu mungkin masuk akal untuk menulis mereka bertingkat dalam kode Anda. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Kadang-kadang ketika berpikir tentang mengubah tertentu, Anda mungkin lupa bahwa struktur yang diberikan dapat disusun bertingkat. diff --git a/translations/id-ID/user-handbook.md b/translations/id-ID/user-handbook.md index fa891695..423914d3 100644 --- a/translations/id-ID/user-handbook.md +++ b/translations/id-ID/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Daftar Isi - * [Pengenalan](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Pengenalan + * [Pengenalan](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Pengenalan Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/it/plugin-handbook.md b/translations/it/plugin-handbook.md index 7e4b0660..3b255255 100644 --- a/translations/it/plugin-handbook.md +++ b/translations/it/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Sommario - * [Introduzione](#introduction) - * [Nozioni di base](#basics) - * [AST](#asts) - * [Stadi primari di Babel](#stages-of-babel) - * [Parse](#parse) - * [Analisi Lessicale](#lexical-analysis) - * [Analisi Sintattica](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Navigazione (traverse)](#traversal) - * [Visitatori (visitor)](#visitors) - * [Percorsi (path)](#paths) - * [Oggetto "path" disponibile nei visitatori](#paths-in-visitors) - * [Stato (state)](#state) - * [Scope](#scopes) - * [Binding](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definizioni](#definitions) - * [Costruttori](#builders) - * [Validatori](#validators) - * [Convertitori](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Scrivere il primo plugin per Babel](#writing-your-first-babel-plugin) - * [Operazioni di trasformazione](#transformation-operations) - * [Navigazione AST](#visiting) - * [Verificare se un nodo è di uno specifico tipo](#check-if-a-node-is-a-certain-type) - * [Verificare se esistono referenze ad un identifier](#check-if-an-identifier-is-referenced) - * [Manipolazione AST](#manipulation) - * [Sostituire un nodo](#replacing-a-node) - * [Sostituire un nodo con più nodi](#replacing-a-node-with-multiple-nodes) - * [Sostituire un nodo con una stringa di codice](#replacing-a-node-with-a-source-string) - * [Inserire un nodo adiacente](#inserting-a-sibling-node) - * [Rimuovere un nodo](#removing-a-node) - * [Sostituire un nodo padre](#replacing-a-parent) - * [Rimuovere un nodo padre](#removing-a-parent) - * [Scope (e variabili)](#scope) - * [Verificare se una variabile locale è associata ad uno scope](#checking-if-a-local-variable-is-bound) - * [Generare un nuovo nome di variabile (UID)](#generating-a-uid) - * [Promuovere la dichiarazione di una variabile ad uno scope padre](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rinominare una variabile (e tutte le sue referenze)](#rename-a-binding-and-its-references) - * [Opzioni per i propri plugin](#plugin-options) - * [Generare nodi (per inserimenti e trasformazioni)](#building-nodes) - * [Best practice](#best-practices) - * [Evitare navigazioni non necessarie dell'AST](#avoid-traversing-the-ast-as-much-as-possible) - * [Aggregare i visitatori quando possibile](#merge-visitors-whenever-possible) - * [Evitare navigazioni programmatiche nidificate](#do-not-traverse-when-manual-lookup-will-do) - * [Ottimizzare i visitatori nidificati](#optimizing-nested-visitors) - * [Essere consapevoli delle strutture nidificate](#being-aware-of-nested-structures) - -# Introduzione + * [Introduzione](#toc-introduction) + * [Nozioni di base](#toc-basics) + * [AST](#toc-asts) + * [Stadi primari di Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Analisi Lessicale](#toc-lexical-analysis) + * [Analisi Sintattica](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Navigazione (traverse)](#toc-traversal) + * [Visitatori (visitor)](#toc-visitors) + * [Percorsi (path)](#toc-paths) + * [Oggetto "path" disponibile nei visitatori](#toc-paths-in-visitors) + * [Stato (state)](#toc-state) + * [Scope](#toc-scopes) + * [Binding](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definizioni](#toc-definitions) + * [Costruttori](#toc-builders) + * [Validatori](#toc-validators) + * [Convertitori](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Scrivere il primo plugin per Babel](#toc-writing-your-first-babel-plugin) + * [Operazioni di trasformazione](#toc-transformation-operations) + * [Navigazione AST](#toc-visiting) + * [Verificare se un nodo è di uno specifico tipo](#toc-check-if-a-node-is-a-certain-type) + * [Verificare se esistono referenze ad un identifier](#toc-check-if-an-identifier-is-referenced) + * [Manipolazione AST](#toc-manipulation) + * [Sostituire un nodo](#toc-replacing-a-node) + * [Sostituire un nodo con più nodi](#toc-replacing-a-node-with-multiple-nodes) + * [Sostituire un nodo con una stringa di codice](#toc-replacing-a-node-with-a-source-string) + * [Inserire un nodo adiacente](#toc-inserting-a-sibling-node) + * [Rimuovere un nodo](#toc-removing-a-node) + * [Sostituire un nodo padre](#toc-replacing-a-parent) + * [Rimuovere un nodo padre](#toc-removing-a-parent) + * [Scope (e variabili)](#toc-scope) + * [Verificare se una variabile locale è associata ad uno scope](#toc-checking-if-a-local-variable-is-bound) + * [Generare un nuovo nome di variabile (UID)](#toc-generating-a-uid) + * [Promuovere la dichiarazione di una variabile ad uno scope padre](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rinominare una variabile (e tutte le sue referenze)](#toc-rename-a-binding-and-its-references) + * [Opzioni per i propri plugin](#toc-plugin-options) + * [Generare nodi (per inserimenti e trasformazioni)](#toc-building-nodes) + * [Best practice](#toc-best-practices) + * [Evitare navigazioni non necessarie dell'AST](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Aggregare i visitatori quando possibile](#toc-merge-visitors-whenever-possible) + * [Evitare navigazioni programmatiche nidificate](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Ottimizzare i visitatori nidificati](#toc-optimizing-nested-visitors) + * [Essere consapevoli delle strutture nidificate](#toc-being-aware-of-nested-structures) + +# Introduzione Babel è un compilatore multiuso e generalista per JavaScript. Nello specifico è un insieme di moduli che possono essere usati per differenti operazioni di analisi statica del codice. @@ -73,11 +73,11 @@ Babel è un compilatore multiuso e generalista per JavaScript. Nello specifico * * * -# Nozioni di base +# Nozioni di base Babel è un compilatore JavaScript, specificamente un compilatore di fonte a fonte, spesso chiamato un "transpiler". Ciò significa che puoi dare Babel del codice JavaScript che viene modificato da Babel, il quale genera del nuovo codice. -## AST +## AST Ognuno di questi passaggi comportano la creazione o l'utilizzo con un [Albero Sintattico Astratto](https://en.wikipedia.org/wiki/Abstract_syntax_tree) o AST. @@ -214,15 +214,15 @@ Ci sono altre proprietà su ogni nodo che Babel genera che descrivono la posizio Queste proprietà `start`, `end`, `loc`, appaiono in ogni singolo Nodo. -## Stadi primari di Babel +## Stadi primari di Babel Le tre fasi primarie di Babel sono **parse**, **trasformare**, **generare**. -### Parse +### Parse Lo stage di **parse** ha come input del codice e come output un AST. Ci sono due fasi di analisi in Babel: [**Analisi Lessicale**](https://en.wikipedia.org/wiki/Lexical_analysis) e [**Analisi Sintattica**](https://en.wikipedia.org/wiki/Parsing). -#### Analisi Lessicale +#### Analisi Lessicale Durante l'analisi lessicale, Babel analizza una stringa di codice e la trasforma in una serie di **tokens**. @@ -264,21 +264,21 @@ Ciascun `type` ha un insieme di proprietà che descrivono il token: In modo simile ai Nodi AST, anche i tokens hanno le proprietà `start`, `end` e `loc`. -#### Analisi Sintattica +#### Analisi Sintattica L'analisi sintattica prende una serie di tokens e costruisce una rappresentazione AST. Utilizzando le informazioni nei token, questa fase li riformatterà come un AST che rappresenta la struttura del codice. -### Transform +### Transform La fase di [trasformazione](https://en.wikipedia.org/wiki/Program_transformation) prende un AST e lo attraversa aggiungendo, modificando e rimuovendo Nodi durante l'attraversamento. Questa è di gran lunga la parte più complessa di Babel o qualsiasi altro compilatore. Questa fase è dove operano i plugin ed è quindi l'argomento principale trattato in questo manuale. Quindi non andremo in profondo in questa fase in questa sezione. -### Generate +### Generate La fase di [generazione del codice](https://en.wikipedia.org/wiki/Code_generation_(compiler)) prende l'AST finale e lo trasforma in una stringa di codice, ed allo stesso tempo crea una [mappa di origine](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Navigazione (traverse) +## Navigazione (traverse) When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ L'oggetto `BinaryExpression` ha le proprietà `operator`, `left` e `right`. L'op Questo processo di attraversamento dell'AST avviene durante lo stage di trasformazione di Babel. -### Visitatori (visitor) +### Visitatori (visitor) Quando si parla di "andare" a un nodo, intendiamo in realtà la **visita** di un nodo. La ragione per che cui usiamo quel termine è perché è sfruttato il concetto di [**visitatore**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Percorsi (path) +### Percorsi (path) Un AST ha generalmente molti nodi, ma come sono collegati tra di loro? Potremmo esporre un oggetto modificabile con pieno accesso, o possiamo semplificare questo con **percorsi**. @@ -485,7 +485,7 @@ E ha anche molti metodi che permettono di aggiungere, aggiornare, spostare e rim In un certo senso, i percorsi sono una rappresentazione **reattiva** della posizione di un nodo nell'albero e di tutte le informazioni sul nodo. Ogni volta che si esegue un metodo che modifica la struttura dell'albero, queste informazioni vengono aggiornate. Babel gestisce tutto questo per voi, per rendere il lavoro con i nodi il più semplice possibile. -#### Oggetto "path" disponibile nei visitatori +#### Oggetto "path" disponibile nei visitatori Quando si dispone di un visitatore che ha un metodo di `Identifier()`, in realtà stai visitando il percorso invece del nodo. In questo modo si lavora principalmente con la rappresentazione reattiva di un nodo anziché il nodo stesso. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### Stato (state) +### Stato (state) Lo "stato" è un nemico quando si parla di trasformazione di AST. Lo stato la morderà più e più volte e le tue ipotesi sullo stato saranno quasi sempre smentite da alcune sintassi che non hai considerato. @@ -572,7 +572,7 @@ const MyVisitor = { Naturalmente, questo è solo un esempio ma viene illustrato come eliminare lo stato globale dai tuoi visitatori. -### Scope +### Scope Adesso introduciamo il concetto di [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript ha uno [scoping lessicale](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), che è una struttura ad albero dove i blocchi creano nuovo scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Binding +#### Binding References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definizioni +### Definizioni Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Costruttori +### Costruttori You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validatori +### Validatori The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Convertitori +### Convertitori > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Scrivere il primo plugin per Babel +# Scrivere il primo plugin per Babel Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Operazioni di trasformazione +# Operazioni di trasformazione -## Navigazione AST +## Navigazione AST -### Verificare se un nodo è di uno specifico tipo +### Verificare se un nodo è di uno specifico tipo If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Verificare se esistono referenze ad un identifier +### Verificare se esistono referenze ad un identifier ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipolazione AST +## Manipolazione AST -### Sostituire un nodo +### Sostituire un nodo ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Sostituire un nodo con più nodi +### Sostituire un nodo con più nodi ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Sostituire un nodo con una stringa di codice +### Sostituire un nodo con una stringa di codice ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserire un nodo adiacente +### Inserire un nodo adiacente ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Rimuovere un nodo +### Rimuovere un nodo ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Sostituire un nodo padre +### Sostituire un nodo padre ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Rimuovere un nodo padre +### Rimuovere un nodo padre ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope (e variabili) +## Scope (e variabili) -### Verificare se una variabile locale è associata ad uno scope +### Verificare se una variabile locale è associata ad uno scope ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generare un nuovo nome di variabile (UID) +### Generare un nuovo nome di variabile (UID) This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Promuovere la dichiarazione di una variabile ad uno scope padre +### Promuovere la dichiarazione di una variabile ad uno scope padre Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rinominare una variabile (e tutte le sue referenze) +### Rinominare una variabile (e tutte le sue referenze) ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Opzioni per i propri plugin +# Opzioni per i propri plugin If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Generare nodi (per inserimenti e trasformazioni) +# Generare nodi (per inserimenti e trasformazioni) When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best practice +# Best practice > I'll be working on this section over the coming weeks. -## Evitare navigazioni non necessarie dell'AST +## Evitare navigazioni non necessarie dell'AST Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Aggregare i visitatori quando possibile +### Aggregare i visitatori quando possibile When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Evitare navigazioni programmatiche nidificate +### Evitare navigazioni programmatiche nidificate It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Ottimizzare i visitatori nidificati +## Ottimizzare i visitatori nidificati When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Essere consapevoli delle strutture nidificate +## Essere consapevoli delle strutture nidificate Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/it/user-handbook.md b/translations/it/user-handbook.md index bb03b8bb..f9f70ddb 100644 --- a/translations/it/user-handbook.md +++ b/translations/it/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Sommario - * [Introduzione](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduzione + * [Introduzione](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduzione Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/ja/README.md b/translations/ja/README.md index 578a44a5..45736554 100644 --- a/translations/ja/README.md +++ b/translations/ja/README.md @@ -1,10 +1,10 @@ # Babel Handbook -This handbook is divided into two parts: +このハンドブックは2つの資料に分かれています。 - * [User Handbook](user-handbook.md) - How to setup/configure Babel and more. - * [Plugin Handbook](plugin-handbook.md) - How to create plugins for Babel. + * [User Handbook](user-handbook.md) - Babel等のセットアップと設定について + * [Plugin Handbook](plugin-handbook.md) - Babelのプラグイン作成について -> For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter. +> 最新の情報を受け取るには、Twitterで[@thejameskyle](https://twitter.com/thejameskyle)をフォローしてください。 -英語以外の翻訳版ハンドブックには、まだ翻訳されていない英語の文章があるかもしれません。 もし翻訳プロジェクトに参加いただける場合には、Crowdinを利用してください。 より詳しい情報は[貢献のためのガイドライン](/CONTRIBUTING.md)を参照してください。 You will find a number of english words that are programming concepts. If these were translated to other languages there would be a lack of consistency and fluency when reading about them. In many cases you will find the literal translation followed by the english term in parenthesis `()`. For example: Abstract Syntax Trees (ASTs). \ No newline at end of file +英語以外の翻訳版ハンドブックには、まだ翻訳されていない英語の文章があるかもしれません。 もし翻訳プロジェクトに参加いただける場合には、Crowdinを利用してください。 より詳しい情報は[貢献のためのガイドライン](/CONTRIBUTING.md)を参照してください。 あなたはプログラミング概念の中で多くの英単語を見るでしょう。 これらの英単語は、他の言語に翻訳してしまうと文章の一貫性と流暢さが損なわれる事となります。 多くの場合は逐語訳の後に`()`の中に元の英単語が書いてあります。 例えば：抽象構文木(ASTs) \ No newline at end of file diff --git a/translations/ja/plugin-handbook.md b/translations/ja/plugin-handbook.md index 99f990f2..1f5d5313 100644 --- a/translations/ja/plugin-handbook.md +++ b/translations/ja/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # 目次 - * [イントロダクション](#introduction) - * [基本](#basics) - * [抽象構文木(ASTs)](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# イントロダクション + * [イントロダクション](#toc-introduction) + * [基本](#toc-basics) + * [抽象構文木(ASTs)](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [スコープ](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [プラグインのオプション](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [ベストプラクティス](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# イントロダクション BabelはJavaScriptのための汎用的で多目的に使用できるコンパイラです。また、様々な静的コード解析に利用するためのモジュールのコレクションでもあります。 @@ -69,15 +69,15 @@ BabelはJavaScriptのための汎用的で多目的に使用できるコンパ Babelを利用することで、より生産的で、より良いコードを書くためのツールを作ることができます。 -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +> ***最新の情報を受け取るには、Twitterで[@thejameskyle](https://twitter.com/thejameskyle)をフォローしてください。*** * * * -# 基本 +# 基本 BabelはJavaScriptのコンパイラ、特にソースからソースへ変換する「トランスパイラ(Transpiler)」と呼ばれる種類のコンパイラです。 つまり、BabelにJavaScriptのコードを与えることで、Babelはコードを変更し新しいコードを生成します。 -## 抽象構文木(ASTs) +## 抽象構文木(ASTs) コードの変換の各ステップでは[抽象構文木(ASTs)](https://en.wikipedia.org/wiki/Abstract_syntax_tree)またはASTを利用します。 @@ -214,15 +214,15 @@ Babelが生成したノードには、元のソースコード上のノードの これらのプロパティには`start`、`end`、`loc`が一つのノードに出現します。 -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## スコープ -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# プラグインのオプション If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# ベストプラクティス > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. @@ -1721,4 +1721,4 @@ class Foo { } ``` -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***最新の情報を受け取るには、Twitterで[@thejameskyle](https://twitter.com/thejameskyle)をフォローしてください。*** \ No newline at end of file diff --git a/translations/ja/user-handbook.md b/translations/ja/user-handbook.md index 3a5daf64..517229dd 100644 --- a/translations/ja/user-handbook.md +++ b/translations/ja/user-handbook.md @@ -1,6 +1,6 @@ # Babel User Handbook -This document covers everything you ever wanted to know about using [Babel](https://babeljs.io) and related tooling. +このドキュメントはあなたが知りたい[Babel](https://babeljs.io)やその関連ツールを使った、その全てをカバーしています。 [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) @@ -8,44 +8,44 @@ This handbook is available in other languages, see the [README](/README.md) for # 目次 - * [イントロダクション](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# イントロダクション - -Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. + * [イントロダクション](#toc-introduction) + * [Babel のセットアップ](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Babel の設定](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [プラグインのオプション](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [静的解析ツール](#toc-static-analysis-tools) + * [Lint](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [フレームワーク](#toc-frameworks) + * [React](#toc-react) + * [テキストエディタ・IDE](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel のサポート](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# イントロダクション + +BabelはJavaScriptのための包括的な多目的コンパイラです。Babelを利用すると、あなたは次世代のJavaScriptを体験するだけではなく、次世代JavaScript用ツールを利用（または作成）することが出来ます。 JavaScript as a language is constantly evolving, with new specs and proposals coming out with new features all the time. Using Babel will allow you to use many of these features years before they are available everywhere. @@ -73,11 +73,11 @@ Further than that, everything in Babel is simply a plugin and anyone can go out Many people do too, the ecosystem that has sprung up around Babel is massive and very diverse. Throughout this handbook I'll be covering both how built-in Babel tools work as well as some useful things from around the community. -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +> ***最新の情報を受け取るには、Twitterで[@thejameskyle](https://twitter.com/thejameskyle)をフォローしてください。*** * * * -# Setting up Babel +# Babel のセットアップ Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -185,7 +185,7 @@ console.log("Hello world!"); If we were to run this with `node index.js` this wouldn't be compiled with Babel. So instead of doing that, we'll setup `babel-register`. -First install `babel-register`. +初めに、`babel-register`をインストールします. ```sh $ npm install --save-dev babel-register @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Babel の設定 You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## プラグインのオプション Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,19 +649,19 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## 静的解析ツール Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Lint One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. -First install `eslint` and `babel-eslint`. +初めに、`eslint` と`babel-eslint`をインストールします. ```sh $ npm install --save-dev eslint babel-eslint @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## フレームワーク All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## テキストエディタ・IDE Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel のサポート Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. @@ -816,4 +816,4 @@ First, try isolating your problem. It's extremely unlikely that every part of yo * * * -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***最新の情報を受け取るには、Twitterで[@thejameskyle](https://twitter.com/thejameskyle)をフォローしてください。*** \ No newline at end of file diff --git a/translations/ko/plugin-handbook.md b/translations/ko/plugin-handbook.md index a1470e6f..41ab460f 100644 --- a/translations/ko/plugin-handbook.md +++ b/translations/ko/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # 목차 - * [소개](#introduction) - * [기본](#basics) - * [추상 구문 트리 (ASTs)](#asts) - * [Babel의 실행 절차](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [첫 Babel 플러그인 작성](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [플러그인 옵션](#plugin-options) - * [Building Nodes](#building-nodes) - * [모범 사례](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# 소개 + * [소개](#toc-introduction) + * [기본](#toc-basics) + * [추상 구문 트리 (ASTs)](#toc-asts) + * [Babel의 실행 절차](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [첫 Babel 플러그인 작성](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [플러그인 옵션](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [모범 사례](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# 소개 Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# 기본 +# 기본 Babel은 JavaScript 컴파일러입니다. 정확히는 소스를 소스로 컴파일하는 "transpiler"로 불리우는 컴파일러입니다. This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## 추상 구문 트리 (ASTs) +## 추상 구문 트리 (ASTs) Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Babel의 실행 절차 +## Babel의 실행 절차 The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# 첫 Babel 플러그인 작성 +# 첫 Babel 플러그인 작성 Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# 플러그인 옵션 +# 플러그인 옵션 If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# 모범 사례 +# 모범 사례 > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/ko/user-handbook.md b/translations/ko/user-handbook.md index a424d52d..90903b8b 100644 --- a/translations/ko/user-handbook.md +++ b/translations/ko/user-handbook.md @@ -1,49 +1,49 @@ # Babel User Handbook -This document covers everything you ever wanted to know about using [Babel](https://babeljs.io) and related tooling. +이 문서는 모든 [Babel](https://babeljs.io)과 관련된 도구를 사용하는 방법에 대해 설명합니다. [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) -This handbook is available in other languages, see the [README](/README.md) for a complete list. +이 핸드북은 다른 언어로도 볼 수 있습니다. 전체 목록은 [README](/README.md)를 참고하세요. # 목차 - * [소개](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# 소개 + * [소개](#toc-introduction) + * [Babel 설정하기](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [프로젝트 내에서 Babel CLI 실행하기](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Babel 컨픽 작성하기](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Babel로 생성된 코드 실행하기](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Babel 컨픽 작성하기 (고급)](#toc-configuring-babel-advanced) + * [수동으로 플러그인 지정하기](#toc-manually-specifying-plugins) + * [플러그인 옵션](#toc-plugin-options) + * [환경에 따른 Babel 커스터마이징](#toc-customizing-babel-based-on-environment) + * [나만의 프리셋 만들기](#toc-making-your-own-preset) + * [Babel과 기타 도구들](#toc-babel-and-other-tools) + * [정적 분석 도구](#toc-static-analysis-tools) + * [코드 검사기 (Linter)](#toc-linting) + * [코드 스타일](#toc-code-style) + * [문서](#toc-documentation) + * [프레임워크](#toc-frameworks) + * [React](#toc-react) + * [텍스트 편집기와 IDE](#toc-text-editors-and-ides) + * [Babel 디버깅하기](#toc-debugging-babel) + * [Babel 지원](#toc-babel-support) + * [Babel 포럼](#toc-babel-forum) + * [Babel 채팅](#toc-babel-chat) + * [Babel 이슈](#toc-babel-issues) + * [멋진 Babel 버그 리포트 생성](#toc-creating-an-awesome-babel-bug-report) + +# 소개 Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Babel 설정하기 Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### 프로젝트 내에서 Babel CLI 실행하기 While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Babel 컨픽 작성하기 You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Babel로 생성된 코드 실행하기 So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Babel 컨픽 작성하기 (고급) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## 수동으로 플러그인 지정하기 Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## 플러그인 옵션 Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## 환경에 따른 Babel 커스터마이징 Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## 나만의 프리셋 만들기 Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel과 기타 도구들 Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## 정적 분석 도구 Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### 코드 검사기 (Linter) One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### 코드 스타일 JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### 문서 Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## 프레임워크 All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## 텍스트 편집기와 IDE Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel 지원 Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel 포럼 [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel 채팅 Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel 이슈 Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### 멋진 Babel 버그 리포트 생성 Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/nl/plugin-handbook.md b/translations/nl/plugin-handbook.md index 9de31ddd..fe690c71 100644 --- a/translations/nl/plugin-handbook.md +++ b/translations/nl/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/nl/user-handbook.md b/translations/nl/user-handbook.md index c269bd9c..cbf010ef 100644 --- a/translations/nl/user-handbook.md +++ b/translations/nl/user-handbook.md @@ -1,49 +1,49 @@ -# Babel User Handbook +# Babel Gebruikershandleiding -This document covers everything you ever wanted to know about using [Babel](https://babeljs.io) and related tooling. +Dit document bevat alles wat je ooit zou willen weten over het gebruik van [Babel](https://babeljs.io) en gerelateerde tooling. [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) -This handbook is available in other languages, see the [README](/README.md) for a complete list. - -# Table of Contents - - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction +Deze gebruikershandleiding is beschikbaar in andere talen, zie de [README](/README.md) voor een volledige lijst. + +# Inhoudsopgave + + * [Introductie](#toc-introduction) + * [Babel instellen](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Babel configureren](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Babel-gegenereerde code uitvoeren](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Babel configureren (Geavanceerd)](#toc-configuring-babel-advanced) + * [Plugins handmatig specificeren](#toc-manually-specifying-plugins) + * [Plugin opties](#toc-plugin-options) + * [Babel aanpassen gebaseerd op je omgeving](#toc-customizing-babel-based-on-environment) + * [Je eigen preset maken](#toc-making-your-own-preset) + * [Babel en andere tools](#toc-babel-and-other-tools) + * [Tools voor statische analyse](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Babel instellen Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Babel configureren You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Babel-gegenereerde code uitvoeren So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Babel configureren (Geavanceerd) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Plugins handmatig specificeren Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin opties Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Babel aanpassen gebaseerd op je omgeving Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Je eigen preset maken Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel en andere tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Tools voor statische analyse Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/no/plugin-handbook.md b/translations/no/plugin-handbook.md index 1ae48634..06e33cb8 100644 --- a/translations/no/plugin-handbook.md +++ b/translations/no/plugin-handbook.md @@ -8,76 +8,76 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction - -Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. - -> Static analysis is the process of analyzing code without executing it. (Analysis of code while executing it is known as dynamic analysis). The purpose of static analysis varies greatly. It can be used for linting, compiling, code highlighting, code transformation, optimization, minification, and much more. - -You can use Babel to build many different types of tools that can help you be more productive and write better programs. - -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** + * [Introduksjon](#toc-introduction) + * [Grunnleggende](#toc-basics) + * [AST(Abstrakte-Syntaks-Tre)](#toc-asts) + * [Ulike Stadier av Babel](#toc-stages-of-babel) + * [Analyse](#toc-parse) + * [Leksikal Analyse](#toc-lexical-analysis) + * [Syntaks Analyse](#toc-syntactic-analysis) + * [Transformasjon](#toc-transform) + * [Generering](#toc-generate) + * [Traversering](#toc-traversal) + * [Gjester](#toc-visitors) + * [Baner](#toc-paths) + * [Besøksbaner til gjester](#toc-paths-in-visitors) + * [Tilstand](#toc-state) + * [Sikte](#toc-scopes) + * [Bindinger](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definisjoner](#toc-definitions) + * [Byggeklosser](#toc-builders) + * [Validatorer](#toc-validators) + * [Formaterere](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Å skrive din første Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformasjon operasjoner](#toc-transformation-operations) + * [Besøking](#toc-visiting) + * [Kontrollere om en node er av en bestemt type](#toc-check-if-a-node-is-a-certain-type) + * [Kontrollere om en node er referert til](#toc-check-if-an-identifier-is-referenced) + * [Manipulasjon](#toc-manipulation) + * [Erstatte en node](#toc-replacing-a-node) + * [Erstatte en node med flere noder](#toc-replacing-a-node-with-multiple-nodes) + * [Erstatte en node med en string fra kilden](#toc-replacing-a-node-with-a-source-string) + * [Sette inn en søsternode](#toc-inserting-a-sibling-node) + * [Fjerne en node](#toc-removing-a-node) + * [Erstatte en forelder](#toc-replacing-a-parent) + * [Fjerne en forelder](#toc-removing-a-parent) + * [Sikte](#toc-scope) + * [Kontrollere om en lokal variabel er bundet](#toc-checking-if-a-local-variable-is-bound) + * [Generere en UID](#toc-generating-a-uid) + * [Skyve en variabeldeklarasjon til et overordnet sikte](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Endre navn på en binding og sine referanser](#toc-rename-a-binding-and-its-references) + * [Plugin alternativer](#toc-plugin-options) + * [Å bygge noder](#toc-building-nodes) + * [Gode øvelser](#toc-best-practices) + * [Unngå å traversere AST-en så mye som mulig](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Kombinere gjester når det er mulig](#toc-merge-visitors-whenever-possible) + * [Ikke bruk traversering når det kan gjøres manuelt](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimalisere nestede gjester](#toc-optimizing-nested-visitors) + * [Vær oppmerksom på struktur og hvordan den er bygd opp](#toc-being-aware-of-nested-structures) + +# Introduksjon + +Babel er en generisk kompilerer, som er brukbar på mange områder. Den er laget for JavaScript. Utenom det, er det en samling av moduler som kan brukes til mange former av statisk analyse. + +> Statisk analyse er prosessen med å analysere koden uten å kjøre den. (Analyse av koden mens utfører, kalles dynamisk analyse). Formålet med statisk analyse varierer mye. Den kan brukes for linting, kompilering, utheving av kode, transformasjon av kode, optimalisering, minifikasjon og mye mer. + +Du kan bruke Babel for å bygge mange forskjellige typer verktøy som kan hjelpe deg å bli mer produktiv å skrive bedre programmer. + +> ***For fremtidige oppdateringer, følg [@thejameskyle](https://twitter.com/thejameskyle) på Twitter.*** * * * -# Basics +# Grunnprinsipp -Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. +Babel er en JavaScript kompilerer, og er en blokk-til-kilde kompilerer, og er ofte kalt en "transpilerer". Dette betyr at du gir Babel JavaScript-kode og Babel endrer koden og genererer ny kode ut igjen. -## ASTs +## AST(Abstrakte-Syntaks-Tre) Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Ulike Stadier av Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Analyse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Leksikal Analyse Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntaks Analyse Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transformasjon The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generering The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversering When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Gjester When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Baner An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Besøksbaner til gjester When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### Tilstand State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Sikte Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindinger References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definisjoner Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Byggeklosser You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validatorer The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Formaterere > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Å skrive din første Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformasjon operasjoner -## Visiting +## Besøking -### Check if a node is a certain type +### Kontrollere om en node er av en bestemt type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Kontrollere om en node er referert til ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulasjon -### Replacing a node +### Erstatte en node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Erstatte en node med flere noder ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Erstatte en node med en string fra kilden ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Sette inn en søsternode ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Fjerne en node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Erstatte en forelder ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Fjerne en forelder ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Sikte -### Checking if a local variable is bound +### Kontrollere om en lokal variabel er bundet ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generere en UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Skyve en variabeldeklarasjon til et overordnet sikte Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Endre navn på en binding og sine referanser ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin alternativer If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Å bygge noder When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Gode øvelser > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Unngå å traversere AST-en så mye som mulig Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Kombinere gjester når det er mulig When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Ikke bruk traversering når det kan gjøres manuelt It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimalisere nestede gjester When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Vær oppmerksom på struktur og hvordan den er bygd opp Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/no/user-handbook.md b/translations/no/user-handbook.md index c269bd9c..e97fd26e 100644 --- a/translations/no/user-handbook.md +++ b/translations/no/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction + * [Introduksjon](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduksjon Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/pl/plugin-handbook.md b/translations/pl/plugin-handbook.md index 1ae48634..17c4d9bd 100644 --- a/translations/pl/plugin-handbook.md +++ b/translations/pl/plugin-handbook.md @@ -1,4 +1,4 @@ -# Babel Plugin Handbook +# Babel Plugin Podręcznik This document covers how to create [Babel](https://babeljs.io) [plugins](https://babeljs.io/docs/advanced/plugins/). @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/pl/user-handbook.md b/translations/pl/user-handbook.md index c269bd9c..4be5d787 100644 --- a/translations/pl/user-handbook.md +++ b/translations/pl/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction + * [Introduction](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/pt-BR/plugin-handbook.md b/translations/pt-BR/plugin-handbook.md index f9854c14..4112ee4a 100644 --- a/translations/pt-BR/plugin-handbook.md +++ b/translations/pt-BR/plugin-handbook.md @@ -8,60 +8,60 @@ Este manual está disponível em outros idiomas, consulte o [arquivo Leia-me](/R # Tabela de Conteúdos - * [Introdução](#introduction) - * [Noções básicas](#basics) - * [ASTs](#asts) - * [Estágios do Babel](#stages-of-babel) - * [Parse](#parse) - * [Análise léxica](#lexical-analysis) - * [Análise sintática](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definições](#definitions) - * [Construtores](#builders) - * [Validadores](#validators) - * [Conversores](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Escrevendo seu primeiro Plugin do Babel](#writing-your-first-babel-plugin) - * [Operações de transformação](#transformation-operations) - * [Visitando](#visiting) - * [Verificar se um nó é um certo tipo](#check-if-a-node-is-a-certain-type) - * [Verifique se um identificador é referenciado](#check-if-an-identifier-is-referenced) - * [Manipulação](#manipulation) - * [Substituindo um nó](#replacing-a-node) - * [Substituindo um nó com vários nós](#replacing-a-node-with-multiple-nodes) - * [Substituindo um nó com uma string](#replacing-a-node-with-a-source-string) - * [Inserir um nó irmão](#inserting-a-sibling-node) - * [Remoção de um nó](#removing-a-node) - * [Substituindo um pai](#replacing-a-parent) - * [Removendo um pai](#removing-a-parent) - * [Escopo](#scope) - * [Verificando se uma variável local está vinculada](#checking-if-a-local-variable-is-bound) - * [Gerando um UID](#generating-a-uid) - * [Empurrando uma declaração de variável para um escopo de pai](#pushing-a-variable-declaration-to-a-parent-scope) - * [Renomear um binding e suas referências](#rename-a-binding-and-its-references) - * [Opções do plugin](#plugin-options) - * [Construindo nós](#building-nodes) - * [Melhores práticas](#best-practices) - * [Evitar cruzar o máximo possível o AST](#avoid-traversing-the-ast-as-much-as-possible) - * [Mesclar os visitantes sempre que possível](#merge-visitors-whenever-possible) - * [Não cruzar quando farão pesquisa manual](#do-not-traverse-when-manual-lookup-will-do) - * [Otimizando os visitantes aninhados](#optimizing-nested-visitors) - * [Estando ciente das estruturas aninhadas](#being-aware-of-nested-structures) - -# Introdução + * [Introdução](#toc-introduction) + * [Noções básicas](#toc-basics) + * [ASTs](#toc-asts) + * [Estágios do Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Análise léxica](#toc-lexical-analysis) + * [Análise sintática](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definições](#toc-definitions) + * [Construtores](#toc-builders) + * [Validadores](#toc-validators) + * [Conversores](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Escrevendo seu primeiro Plugin do Babel](#toc-writing-your-first-babel-plugin) + * [Operações de transformação](#toc-transformation-operations) + * [Visitando](#toc-visiting) + * [Verificar se um nó é um certo tipo](#toc-check-if-a-node-is-a-certain-type) + * [Verifique se um identificador é referenciado](#toc-check-if-an-identifier-is-referenced) + * [Manipulação](#toc-manipulation) + * [Substituindo um nó](#toc-replacing-a-node) + * [Substituindo um nó com vários nós](#toc-replacing-a-node-with-multiple-nodes) + * [Substituindo um nó com uma string](#toc-replacing-a-node-with-a-source-string) + * [Inserir um nó irmão](#toc-inserting-a-sibling-node) + * [Remoção de um nó](#toc-removing-a-node) + * [Substituindo um pai](#toc-replacing-a-parent) + * [Removendo um pai](#toc-removing-a-parent) + * [Escopo](#toc-scope) + * [Verificando se uma variável local está vinculada](#toc-checking-if-a-local-variable-is-bound) + * [Gerando um UID](#toc-generating-a-uid) + * [Empurrando uma declaração de variável para um escopo de pai](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Renomear um binding e suas referências](#toc-rename-a-binding-and-its-references) + * [Opções do plugin](#toc-plugin-options) + * [Construindo nós](#toc-building-nodes) + * [Melhores práticas](#toc-best-practices) + * [Evitar cruzar o máximo possível o AST](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Mesclar os visitantes sempre que possível](#toc-merge-visitors-whenever-possible) + * [Não cruzar quando farão pesquisa manual](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Otimizando os visitantes aninhados](#toc-optimizing-nested-visitors) + * [Estando ciente das estruturas aninhadas](#toc-being-aware-of-nested-structures) + +# Introdução Babel é um compilador genérico de múltiplos propósito para JavaScript. Mais do que isso, é uma coleção de módulos que podem ser usados de muitas formas diferentes de análise estática. @@ -73,11 +73,11 @@ Você pode usar Babel para construir vários tipos de ferramentas que podem ajud * * * -# Noções básicas +# Noções básicas Babel é um compilador JavaScript, especificamente um compilador de código para código, muitas vezes chamado de "transpiler". Isto significa que você dá ao Babel algum código JavaScript, ele modifica o código e gera um novo código de volta. -## ASTs +## ASTs Cada um destes passos envolvem criação ou trabalho com uma [Árvore de Sintaxe Abstrata](https://en.wikipedia.org/wiki/Abstract_syntax_tree) ou AST. @@ -116,7 +116,7 @@ Este mesmo programa pode ser representado como uma lista assim: - name: n ``` -Or as a JavaScript Object like this: +Ou como um JSON como este: ```js { @@ -150,7 +150,7 @@ Or as a JavaScript Object like this: } ``` -You'll notice that each level of the AST has a similar structure: +Você observará que cada nível da AST tem uma estrutura semelhante: ```js { @@ -177,11 +177,11 @@ You'll notice that each level of the AST has a similar structure: } ``` -> Note: Some properties have been removed for simplicity. +> Nota: Algumas propriedades foram removidas para manter a simplicidade. -Each of these are known as a **Node**. An AST can be made up of a single Node, or hundreds if not thousands of Nodes. Together they are able to describe the syntax of a program that can be used for static analysis. +Cada um deles são conhecidos como um **nó**. Um AST pode ser composta por um único nó, ou centenas, senão milhares de nós. Juntos, eles são capazes de descrever a sintaxe de um programa que pode ser usado para análise estática. -Every Node has this interface: +Cada nó tem esta interface: ```typescript interface Node { @@ -189,9 +189,9 @@ interface Node { } ``` -The `type` field is a string representing the type of Node the object is (ie. `"FunctionDeclaration"`, `"Identifier"`, or `"BinaryExpression"`). Each type of Node defines an additional set of properties that describe that particular node type. +O `tipo` de campo é uma seqüência de caracteres que representa o tipo do nó do objeto (ex. `"FunctionDeclaration"`, `"Identifier"` ou `"BinaryExpression"`). Cada tipo de nó define um conjunto adicional de propriedades que descrevem o tipo de nó específico. -There are additional properties on every Node that Babel generates which describe the position of the Node in the original source code. +Existem propriedades adicionais em cada nó que Babel gera que descrevem a posição do nó no código-fonte original. ```js { @@ -212,21 +212,21 @@ There are additional properties on every Node that Babel generates which describ } ``` -These properties `start`, `end`, `loc`, appear in every single Node. +Estas propriedades `start`, `end`, `loc`, aparecem em cada nó. -## Estágios do Babel +## Estágios do Babel -The three primary stages of Babel are **parse**, **transform**, **generate**. +Os três estágios primários de Babel são **parse**, **transform**, **generate**. -### Parse +### Parse -The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). +O estágio de **parse**, paga o código e produz um AST. Existem duas fases de análise de Babel: [**Análise léxica**](https://en.wikipedia.org/wiki/Lexical_analysis) e [**Análise sintática**](https://en.wikipedia.org/wiki/Parsing). -#### Análise léxica +#### Análise léxica -Lexical Analysis will take a string of code and turn it into a stream of **tokens**. +Análise lexical pega uma sequência de caracteres de código e o transforma em um fluxo de **tokens**. -You can think of tokens as a flat array of language syntax pieces. +Você pode pensar nos tokens como uma matriz plana de pedaços de sintaxe de linguagem. ```js n * n; @@ -236,12 +236,11 @@ n * n; [ { type: { ... }, value: "n", start: 0, end: 1, loc: { ... } }, { type: { ... }, value: "*", start: 2, end: 3, loc: { ... } }, - { type: { ... }, value: "n", start: 4, end: 5, loc: { ... } }, - ... + { type: { ... }, value: "n", start: 4, end: 5, loc: { ... } }, ... ] ``` -Each of the `type`s here have a set of properties describing the token: +Cada um dos `tipos` tem um conjunto de propriedades que descrevem o token: ```js { @@ -262,27 +261,27 @@ Each of the `type`s here have a set of properties describing the token: } ``` -Like AST nodes they also have a `start`, `end`, and `loc`. +Como nós de AST também têm um `start`, `end` e `loc`. -#### Análise sintática +#### Análise sintática -Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. +Análise sintática irá levar a um fluxo de tokens e transformá-lo em uma representação de AST. Usando as informações de tokens, esta fase será reformatá-los como um AST que representa a estrutura do código de uma forma que torna mais fácil trabalhar. -### Transform +### Transform -The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. +O estágio de [transform](https://en.wikipedia.org/wiki/Program_transformation) atravessa um AST, adicionando, atualizando e removendo os nós junto. Esta é de longe a parte mais complexa de Babel ou qualquer compilador. Isto é onde operam os plugins e então será o assunto principal deste manual. Então não mergulharemos tão profundamente agora. -### Generate +### Generate -The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). +O estágio de [geração de código](https://en.wikipedia.org/wiki/Code_generation_(compiler)) leva a AST final e transforma de volta em uma seqüência de caracteres do código, criando também [mapa da fonte](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). -Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. +Geração de código é muito simples: você percorre através da AST primeiro, e constroi uma sequência de caracteres que representa o código transformado. -## Traversal +## Traversal -When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. +Quando você deseja transformar um AST... você tem que [percorrer (traverse) a árvore](https://en.wikipedia.org/wiki/Tree_traversal) recursivamente. -Say we have the type `FunctionDeclaration`. It has a few properties: `id`, `params`, and `body`. Each of them have nested nodes. +Digamos que temos um nó do tipo `FunctionDeclaration`. Ele tem algumas propriedades como: `id`, `params` e `body`. Cada um deles possui seus próprios nós aninhados. ```js { @@ -316,23 +315,23 @@ Say we have the type `FunctionDeclaration`. It has a few properties: `id`, `para } ``` -So we start at the `FunctionDeclaration` and we know its internal properties so we visit each of them and their children in order. +Então começamos no nó `FunctionDeclaration` e sabemos suas propriedades internas, logo, podemos visitar cada uma delas e seus filhos na sequência. -Next we go to `id` which is an `Identifier`. `Identifier`s don't have any child node properties so we move on. +Depois vamos para o `id`, que é um `Identifier`.`Identifier` e não tem quaisquer propriedades do nó filho então podemos continuar. -After that is `params` which is an array of nodes so we visit each of them. In this case it's a single node which is also an `Identifier` so we move on. +Depois disso temos a propriedade `params`, que é uma matriz de nós. Nós os percorreremos, visitando cada um deles. Neste caso `params` possui um único nó, que é também um <0>Identifier, então podemos continuar. -Then we hit `body` which is a `BlockStatement` with a property `body` that is an array of Nodes so we go to each of them. +Então encontramos o `body` que é um `BlockStatement` com uma propriedade `body` que é uma matriz de nós, então nós vamos a cada um deles. -The only item here is a `ReturnStatement` node which has an `argument`, we go to the `argument` and find a `BinaryExpression`. +O único item que aqui é um nó `ReturnStatement` que tem um `argument`, nós vamos para o `argument` e encontramos um `BinaryExpression`. -The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator isn't a node, just a value, so we don't go to it, and instead just visit `left` and `right`. +O `BinaryExpression` tem uma propriedade `operator`, uma `left` e uma `right`. O operador não é um nó, apenas um valor, então não vamos até ele. Em vez disso, apenas visitamos as propriedades `left` e `right`. -This traversal process happens throughout the Babel transform stage. +Este processo de percorrer (traverse) acontece durante toda a fase de transformação de Babel. -### Visitors +### Visitors -When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). +Quando falamos sobre "ir" para um nó, na verdade queremos dizer que estamos **visitando** eles. A razão pela qual nós usamos esse termo está ligada ao conceito do design pattern [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern), usado frequentemente. Visitors are a pattern used in AST traversal across languages. Simply put they are an object with methods defined for accepting particular node types in a tree. That's a bit abstract so let's look at an example. @@ -418,7 +417,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +484,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +506,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +571,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +645,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +698,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +752,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +786,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +811,7 @@ traverse(ast, { }); ``` -### Definições +### Definições Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +836,7 @@ defineType("BinaryExpression", { }); ``` -### Construtores +### Construtores You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +875,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validadores +### Validadores The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +913,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Conversores +### Conversores > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +958,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +987,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Escrevendo seu primeiro Plugin do Babel +# Escrevendo seu primeiro Plugin do Babel Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1112,11 @@ Awesome! Our very first Babel plugin. * * * -# Operações de transformação +# Operações de transformação -## Visitando +## Visitando -### Verificar se um nó é um certo tipo +### Verificar se um nó é um certo tipo If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1152,7 @@ BinaryExpression(path) { } ``` -### Verifique se um identificador é referenciado +### Verifique se um identificador é referenciado ```js Identifier(path) { @@ -1173,9 +1172,9 @@ Identifier(path) { } ``` -## Manipulação +## Manipulação -### Substituindo um nó +### Substituindo um nó ```js BinaryExpression(path) { @@ -1192,7 +1191,7 @@ BinaryExpression(path) { } ``` -### Substituindo um nó com vários nós +### Substituindo um nó com vários nós ```js ReturnStatement(path) { @@ -1215,7 +1214,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Substituindo um nó com uma string +### Substituindo um nó com uma string ```js FunctionDeclaration(path) { @@ -1235,7 +1234,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserir um nó irmão +### Inserir um nó irmão ```js FunctionDeclaration(path) { @@ -1254,7 +1253,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Remoção de um nó +### Remoção de um nó ```js FunctionDeclaration(path) { @@ -1268,7 +1267,7 @@ FunctionDeclaration(path) { - } ``` -### Substituindo um pai +### Substituindo um pai ```js BinaryExpression(path) { @@ -1285,7 +1284,7 @@ BinaryExpression(path) { } ``` -### Removendo um pai +### Removendo um pai ```js BinaryExpression(path) { @@ -1299,9 +1298,9 @@ BinaryExpression(path) { } ``` -## Escopo +## Escopo -### Verificando se uma variável local está vinculada +### Verificando se uma variável local está vinculada ```js FunctionDeclaration(path) { @@ -1323,7 +1322,7 @@ FunctionDeclaration(path) { } ``` -### Gerando um UID +### Gerando um UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1335,7 @@ FunctionDeclaration(path) { } ``` -### Empurrando uma declaração de variável para um escopo de pai +### Empurrando uma declaração de variável para um escopo de pai Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1355,7 @@ FunctionDeclaration(path) { + }; ``` -### Renomear um binding e suas referências +### Renomear um binding e suas referências ```js FunctionDeclaration(path) { @@ -1390,7 +1389,7 @@ FunctionDeclaration(path) { * * * -# Opções do plugin +# Opções do plugin If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1423,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Construindo nós +# Construindo nós When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1534,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Melhores práticas +# Melhores práticas > I'll be working on this section over the coming weeks. -## Evitar cruzar o máximo possível o AST +## Evitar cruzar o máximo possível o AST Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Mesclar os visitantes sempre que possível +### Mesclar os visitantes sempre que possível When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1575,7 @@ path.traverse({ }); ``` -### Não cruzar quando farão pesquisa manual +### Não cruzar quando farão pesquisa manual It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1605,7 @@ const MyVisitor = { }; ``` -## Otimizando os visitantes aninhados +## Otimizando os visitantes aninhados When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1674,7 @@ const MyVisitor = { }; ``` -## Estando ciente das estruturas aninhadas +## Estando ciente das estruturas aninhadas Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/pt-BR/user-handbook.md b/translations/pt-BR/user-handbook.md index 5a87334c..89351844 100644 --- a/translations/pt-BR/user-handbook.md +++ b/translations/pt-BR/user-handbook.md @@ -8,42 +8,42 @@ Este manual está disponível em outros idiomas, consulte o [arquivo Leia-me](/R # Tabela de Conteúdos - * [Introdução](#introduction) - * [Configurando o Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Executando o Babel CLI em um projeto](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configurando o Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introdução + * [Introdução](#toc-introduction) + * [Configurando o Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Executando o Babel CLI em um projeto](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configurando o Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introdução Babel é um compilador genérico multifuncional de JavaScript. Usando o Babel, você pode usar (e criar) a próxima geração do JavaScript, além da próxima geração da ferramenta do JavaScript. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Configurando o Babel +# Configurando o Babel Já que a comunidade JavaScript não possui uma única ferramenta de construção, framework, plataforma, etc., Babel possui integrações oficiais para todas as maiores ferramentas. Tudo desde Gulp até Browserify, de Ember até Meteor, não importa como está sua configuração, existe provavelmente uma integração oficial. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Nota:** Esse guia usa ferramentas de linha de comando como `node` and `npm`. Antes de seguir adiante, você deve familiarizar-se com essas ferramentas. -## `babel-cli` +## `babel-cli` O Cliente do Babel é uma maneira simples de compilar arquivos com o Babel na linha de comando. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Executando o Babel CLI em um projeto +### Executando o Babel CLI em um projeto Embora você *possa* instalar o Cliente do Babel globalmente na sua máquina, é mais recomendável fazer a instalação **localmente** projeto por projeto. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configurando o Babel +# Configurando o Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/pt-PT/README.md b/translations/pt-PT/README.md index c09f34b5..bfb5f911 100644 --- a/translations/pt-PT/README.md +++ b/translations/pt-PT/README.md @@ -1,10 +1,10 @@ -# Babel Handbook +# Manual de Babel -This handbook is divided into two parts: +Este manual está dividido em duas partes: - * [User Handbook](user-handbook.md) - How to setup/configure Babel and more. - * [Plugin Handbook](plugin-handbook.md) - How to create plugins for Babel. + * [Manual do utilizador](user-handbook.md) - Como configurar o Babel e mais. + * [Manual de Plugins](plugin-handbook.md) - Como criar plugins para o Babel. -> For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter. +> Para futuras atualizações, siga [@thejameskyle](https://twitter.com/thejameskyle) no Twitter. -If you are reading a non-english translation of this handbook you may still find english sections that have not yet been translated. If you would like to contribute to one of the translations you must do so through Crowdin. Please read the [contributing guidelines](/CONTRIBUTING.md) for more information. You will find a number of english words that are programming concepts. If these were translated to other languages there would be a lack of consistency and fluency when reading about them. In many cases you will find the literal translation followed by the english term in parenthesis `()`. For example: Abstract Syntax Trees (ASTs). \ No newline at end of file +Se está a ler uma tradução não inglesa deste manual é possível que ainda encontre algumas secções em inglês que ainda não foram traduzidas. Se gostava de contribuir para uma das traduções terá de o fazer através do Crowdin. Por favor leia as [instruções para contribuir](/CONTRIBUTING.md) para mais informações. Irá encontrar uma série de palavras em Inglês que são conceitos de programação. Se estas palavras fossem traduzidas para outras línguas seria dificil de manter a consistência e coêrencia ao ler sobre elas. Em muitos casos, você irá encontrar a tradução literal, seguida do termo inglês em parênteses`()`. Por exemplo: Árvores de Sintaxe Abstractas (Abstract Syntax Trees). \ No newline at end of file diff --git a/translations/pt-PT/plugin-handbook.md b/translations/pt-PT/plugin-handbook.md index 1ae48634..328ad99f 100644 --- a/translations/pt-PT/plugin-handbook.md +++ b/translations/pt-PT/plugin-handbook.md @@ -1,67 +1,67 @@ -# Babel Plugin Handbook +# Manual de Plugins de Babel -This document covers how to create [Babel](https://babeljs.io) [plugins](https://babeljs.io/docs/advanced/plugins/). +Este documento explica como criar [plugins](https://babeljs.io/docs/advanced/plugins/) para o [Babel](https://babeljs.io). [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) -This handbook is available in other languages, see the [README](/README.md) for a complete list. - -# Table of Contents - - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction +Este manual está disponível noutras línguas. Uma lista completa de todas as traduções pode ser encontrada no [README](/README.md). + +# Índice + + * [Introdução](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introdução Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -69,15 +69,15 @@ Babel is a generic multi-purpose compiler for JavaScript. More than that it is a You can use Babel to build many different types of tools that can help you be more productive and write better programs. -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +> ***Para futuras atualizações, siga [@thejameskyle](https://twitter.com/thejameskyle) no Twitter.*** * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. @@ -1721,4 +1721,4 @@ class Foo { } ``` -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***Para futuras atualizações, siga [@thejameskyle](https://twitter.com/thejameskyle) no Twitter.*** \ No newline at end of file diff --git a/translations/pt-PT/user-handbook.md b/translations/pt-PT/user-handbook.md index c269bd9c..186a3c5c 100644 --- a/translations/pt-PT/user-handbook.md +++ b/translations/pt-PT/user-handbook.md @@ -1,49 +1,49 @@ -# Babel User Handbook +# Manual do utilizador de Babel -This document covers everything you ever wanted to know about using [Babel](https://babeljs.io) and related tooling. +Este documento abrange tudo o que sempre quis saber sobre o uso de [Babel](https://babeljs.io) e relacionadas com o trabalho feito com ferramentas. [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) -This handbook is available in other languages, see the [README](/README.md) for a complete list. - -# Table of Contents - - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction +Este manual está disponível noutras línguas. Uma lista completa de todas as traduções pode ser encontrada no [README](/README.md). + +# Índice + + * [Introdução](#toc-introduction) + * [Configurar o Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introdução Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -73,11 +73,11 @@ Further than that, everything in Babel is simply a plugin and anyone can go out Many people do too, the ecosystem that has sprung up around Babel is massive and very diverse. Throughout this handbook I'll be covering both how built-in Babel tools work as well as some useful things from around the community. -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +> ***Para futuras atualizações, siga [@thejameskyle](https://twitter.com/thejameskyle) no Twitter.*** * * * -# Setting up Babel +# Configurar o Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -98,15 +98,15 @@ $ npm install --global babel-cli We can compile our first file like so: ```sh -$ babel my-file.js +$ babel o-meu-ficheiro.js ``` This will dump the compiled output directly into your terminal. To write it to a file we'll specify an `--out-file` or `-o`. ```sh -$ babel example.js --out-file compiled.js -# or -$ babel example.js -o compiled.js +$ babel examplo.js --out-file compilado.js +# ou +$ babel examplo.js -o compilado.js ``` If we want to compile a whole directory into a new directory we can do so using `--out-dir` or `-d`. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. @@ -816,4 +816,4 @@ First, try isolating your problem. It's extremely unlikely that every part of yo * * * -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***Para futuras atualizações, siga [@thejameskyle](https://twitter.com/thejameskyle) no Twitter.*** \ No newline at end of file diff --git a/translations/ro/plugin-handbook.md b/translations/ro/plugin-handbook.md index 85c3c5eb..f4c3604b 100644 --- a/translations/ro/plugin-handbook.md +++ b/translations/ro/plugin-handbook.md @@ -8,60 +8,60 @@ Acest manual este disponibil și în alte limbi, a se vedea [README](/README.md) # Cuprins - * [Introducere](#introduction) - * [Concepte de bază](#basics) - * [ASTs](#asts) - * [Etapele Babel](#stages-of-babel) - * [Analiză](#parse) - * [Analiză Lexicală](#lexical-analysis) - * [Analiză Sintactică](#syntactic-analysis) - * [Transformare](#transform) - * [Generare](#generate) - * [Traversare](#traversal) - * [Vizitatori (Visitors)](#visitors) - * [Trasee (Paths)](#paths) - * [Trasee în Vizitatori (Paths in Visitors)](#paths-in-visitors) - * [Stare](#state) - * [Domenii (Scopes)](#scopes) - * [Legături (Bindings)](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definiții](#definitions) - * [Constructori](#builders) - * [Validatori](#validators) - * [Convertori](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Scrierea primului Plugin Babel](#writing-your-first-babel-plugin) - * [Operații de Transformare](#transformation-operations) - * [Vizitare (Visiting)](#visiting) - * [Verificare dacă un nod este de un anumit tip](#check-if-a-node-is-a-certain-type) - * [Verificare dacă un identificator are referință](#check-if-an-identifier-is-referenced) - * [Manipulare](#manipulation) - * [Înlocuirea unui nod](#replacing-a-node) - * [Înlocuirea unui nod cu mai multe noduri](#replacing-a-node-with-multiple-nodes) - * [Înlocuirea unui nod cu un șir de caractere sursă](#replacing-a-node-with-a-source-string) - * [Inserarea unui nod pe același nivel](#inserting-a-sibling-node) - * [Ștergerea unui nod](#removing-a-node) - * [Înlocuirea unui părinte](#replacing-a-parent) - * [Ștergerea unui părinte](#removing-a-parent) - * [Domeniu (Scope)](#scope) - * [Verificare dacă o variabilă locală este legată](#checking-if-a-local-variable-is-bound) - * [Generarea unui UID](#generating-a-uid) - * [Mutarea unei declarații de variabilă într-un domeniu părinte](#pushing-a-variable-declaration-to-a-parent-scope) - * [Redenumirea unei legături și a referințelor sale](#rename-a-binding-and-its-references) - * [Opțiuni de plugin](#plugin-options) - * [Construirea nodurilor](#building-nodes) - * [Practici preferate](#best-practices) - * [Evitați traversarea AST pe cât posibil](#avoid-traversing-the-ast-as-much-as-possible) - * [Îmbinarea vizitatorilor ori de câte ori este posibil](#merge-visitors-whenever-possible) - * [Evitați traversarea când o căutare manuală este suficientă](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizarea vizitatorilor imbricați](#optimizing-nested-visitors) - * [Atenție la structuri imbricate](#being-aware-of-nested-structures) - -# Introducere + * [Introducere](#toc-introduction) + * [Concepte de bază](#toc-basics) + * [ASTs](#toc-asts) + * [Etapele Babel](#toc-stages-of-babel) + * [Analiză](#toc-parse) + * [Analiză Lexicală](#toc-lexical-analysis) + * [Analiză Sintactică](#toc-syntactic-analysis) + * [Transformare](#toc-transform) + * [Generare](#toc-generate) + * [Traversare](#toc-traversal) + * [Vizitatori (Visitors)](#toc-visitors) + * [Trasee (Paths)](#toc-paths) + * [Trasee în Vizitatori (Paths in Visitors)](#toc-paths-in-visitors) + * [Stare](#toc-state) + * [Domenii (Scopes)](#toc-scopes) + * [Legături (Bindings)](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definiții](#toc-definitions) + * [Constructori](#toc-builders) + * [Validatori](#toc-validators) + * [Convertori](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Scrierea primului Plugin Babel](#toc-writing-your-first-babel-plugin) + * [Operații de Transformare](#toc-transformation-operations) + * [Vizitare (Visiting)](#toc-visiting) + * [Verificare dacă un nod este de un anumit tip](#toc-check-if-a-node-is-a-certain-type) + * [Verificare dacă un identificator are referință](#toc-check-if-an-identifier-is-referenced) + * [Manipulare](#toc-manipulation) + * [Înlocuirea unui nod](#toc-replacing-a-node) + * [Înlocuirea unui nod cu mai multe noduri](#toc-replacing-a-node-with-multiple-nodes) + * [Înlocuirea unui nod cu un șir de caractere sursă](#toc-replacing-a-node-with-a-source-string) + * [Inserarea unui nod pe același nivel](#toc-inserting-a-sibling-node) + * [Ștergerea unui nod](#toc-removing-a-node) + * [Înlocuirea unui părinte](#toc-replacing-a-parent) + * [Ștergerea unui părinte](#toc-removing-a-parent) + * [Domeniu (Scope)](#toc-scope) + * [Verificare dacă o variabilă locală este legată](#toc-checking-if-a-local-variable-is-bound) + * [Generarea unui UID](#toc-generating-a-uid) + * [Mutarea unei declarații de variabilă într-un domeniu părinte](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Redenumirea unei legături și a referințelor sale](#toc-rename-a-binding-and-its-references) + * [Opțiuni de plugin](#toc-plugin-options) + * [Construirea nodurilor](#toc-building-nodes) + * [Practici preferate](#toc-best-practices) + * [Evitați traversarea AST pe cât posibil](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Îmbinarea vizitatorilor ori de câte ori este posibil](#toc-merge-visitors-whenever-possible) + * [Evitați traversarea când o căutare manuală este suficientă](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizarea vizitatorilor imbricați](#toc-optimizing-nested-visitors) + * [Atenție la structuri imbricate](#toc-being-aware-of-nested-structures) + +# Introducere Babel este un compilator generic multi-scop pentru JavaScript. Mai mult decât atât, este o colecție de module care pot fi utilizate pentru diverse tipuri de analiză statică. @@ -73,11 +73,11 @@ Puteți utiliza Babel pentru a construi diverse tipuri de instrumente care vă p * * * -# Concepte de bază +# Concepte de bază Babel este un compilator de JavaScript, mai exact un compilator sursă-la-sursă, deseori numit un "transpiler". Asta înseamnă că dacă îi pasezi cod JavaScript, Babel modifică codul, și generează cod nou. -## ASTs +## ASTs Fiecare dintre acești pași implică crearea sau lucrul cu un [Arbore Abstract de Sintaxă](https://en.wikipedia.org/wiki/Abstract_syntax_tree) sau AST. @@ -214,15 +214,15 @@ Există proprietăţi suplimentare pe fiecare Nod, generate de Babel, care descr Aceste proprietăţi `start`, `end`, `loc`, apar în fiecare Nod. -## Etapele Babel +## Etapele Babel Cele trei etape principale ale Babel sunt **analiză**, **transformare**, **generare**. -### Analiză +### Analiză Etapa de **analiză**, primeste codul şi produce AST-ul. Există două faze ale analizei în Babel: [**Analiza lexicală**](https://en.wikipedia.org/wiki/Lexical_analysis) şi [**Analiza sintactică**](https://en.wikipedia.org/wiki/Parsing). -#### Analiză Lexicală +#### Analiză Lexicală Analiza lexicală primeste un şir de cod şi-l transformă într-un flux de simboluri (**tokens**). @@ -264,21 +264,21 @@ Fiecare `type` are un set de proprietăţi care descrie token-ul: La fel ca nodurile AST, acestea conțin `start`, `end`, și `loc`. -#### Analiză Sintactică +#### Analiză Sintactică Analiza sintactică primește un flux de token-uri şi-l transformă într-o reprezentare AST. Folosind informaţiile din token-uri, această fază le va reformata ca un AST care reprezintă structura codului într-un mod care este mai uşor de utilizat. -### Transformare +### Transformare Etapa de [Transformare](https://en.wikipedia.org/wiki/Program_transformation) primește un AST pe care-l traversează, adăugă, actualizează şi sterge noduri. Această etapă este de departe cea mai complexă din Babel sau din orice alt compilator. Acesta este locul în care plugin-urile acționează de fapt, aşadar va fi subiectul majorității capitolelor din acest manual. Nu vom intra prea adânc în detalii pentru moment. -### Generare +### Generare Etapa de [generare de cod](https://en.wikipedia.org/wiki/Code_generation_(compiler)) primește AST-ul final şi-l transformă înapoi într-un şir de cod, creând şi [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Generarea de cod este destul de simplă: se traversează AST-ul și se construiește un şir de caractere care reprezintă codul transformat. -## Traversare +## Traversare Atunci când doriţi să transformați un AST trebuie să-l [traversați](https://en.wikipedia.org/wiki/Tree_traversal) recursiv. @@ -330,7 +330,7 @@ Singurul element de aici este un nod `ReturnStatement`, care are un `argument`, Acest proces de traversare se întâmplă de-a lungul etapei de transformare Babel. -### Vizitatori (Visitors) +### Vizitatori (Visitors) Atunci când vorbim despre "a merge" la un nod, ne referim de fapt la a-l **vizita**. Motivul pentru care vom folosi acest termen este pentru că există acest concept de [**vizitator**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Trasee (Paths) +### Trasee (Paths) AST o are în general multe Noduri, dar cum se relaționează ele unul la altul? Am putea avea un singur obiect mutabil gigant, care să-l manipulăm şi să avem acces deplin la el, sau putem simplifica acest lucru cu Trasee (**Paths**). @@ -485,7 +485,7 @@ Precum şi foarte multe metode legate de adăugarea, actualizarea, mutarea, şi Într-un anumit sens, traseele sunt o reprezentare **reactivă** a poziţiei unui nod în arbore şi multe alte informatii despre nod. Ori de câte ori apelați o metodă care modifică arborele, această informaţie este actualizată. Babel gestionează toate acestea pentru a face lucrul cu noduri cât mai ușor posibil. -#### Trasee în Vizitatori (Paths in Visitors) +#### Trasee în Vizitatori (Paths in Visitors) Când aveţi un vizitator care are o metodă `Identifier()`, de fapt se vizitează traseul, nu nodul. În acest fel se lucrează cu reprezentarea reactivă a nodului, nu cu nodul în sine. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### Stare +### Stare Starea este duşmanul transformării AST-ului. Starea îți va crea mari probleme şi ipotezele tale despre stare vor fi aproape întotdeauna greşite, din cauza unei sintaxe care nu ai luat-o în considerare. @@ -572,7 +572,7 @@ const MyVisitor = { Desigur, acesta este un exemplu teoretic, însă demonstrează cum să eliminăm starea globală din vizitatori. -### Domenii (Scopes) +### Domenii (Scopes) În continuare vom introduce conceptul de [**domeniu**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript utilizează [domeniu lexical](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), care este o structură de arbore, în care fiecare bloc crează un nou domeniu. @@ -646,7 +646,7 @@ Crearea unui domeniu nou implică pasarea unui traseu şi a unui domeniu părint Odată ce am făcut acest lucru, există tot felul de metode ce le putem utiliza pe domenii. Însă le vom examina mai târziu. -#### Legături (Bindings) +#### Legături (Bindings) Toate referinţele aparţin unui anumit domeniu; această relaţie este cunoscută sub denumirea de **legătură**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel este de fapt o colecţie de module. În această secţiune vom trece prin cele mai importante, explicând la ce ajută şi cum se utilizează. > Notă: Acest document nu este un înlocuitor pentru documentaţia detaliată a API-ului, care va fi disponibilă în altă parte în scurt timp. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon este analizorul din Babel. A început ca o bifurcație din Acorn, este rapid, simplu de utilizat, are o arhitectură bazată pe plugin-uri pentru caracteristici neconvenţionale (precum şi viitoarele standarde). @@ -753,7 +753,7 @@ Din moment ce Babylon este construit cu o arhitectură bazată pe plugin-uri, ex Pentru a vedea o listă completă de plugin-uri, examinați [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) Modulul de Traversare Babel conține starea generală a arborelui, şi este responsabil pentru înlocuirea, ștergerea şi adăugarea de noduri. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types este o librărie de utilitare, similară cu Lodash, pentru nodurile AST. Conține metode pentru construirea, validarea şi conversia nodurilor AST. Este util pentru curățarea logicii AST cu metode utilitare bine gândite. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definiții +### Definiții Babel Types conține definiţii pentru fiecare tip de nod, și informaţii cu privire la ce proprietăţile aparţin cui, ce valori sunt valide, cum se construiește un nod, cum ar trebui traversat nodul şi pseudonime ale nodului. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Constructori +### Constructori Veţi observa mai sus că definiţia pentru `BinaryExpression` are un câmp `builder`. @@ -876,7 +876,7 @@ a * b Constructorii, de asemenea, vor valida nodurile pe care le crează şi aruncă erori descriptive dacă sunt folosiți necorespunzător. Ceea ce ne conduce la următorul tip de metodă. -### Validatori +### Validatori Definiția pentru `BinaryExpression` include informații privind cămpurile (`fields`) nodului şi cum să le validăm. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Convertori +### Convertori > [WIP] în lucru -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator este generatorul de cod pentru Babel. Primește un AST şi îl transformă în cod cu sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template este un alt modul micuț dar incredibil de util. Vă permite să scrieți şiruri de cod cu substituenţi care îi puteţi folosi în loc să construiți manual un AST uriaș. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Scrierea primului Plugin Babel +# Scrierea primului Plugin Babel Acum că sunteţi familiarizați cu toate elementele de bază din Babel, haideţi să le utilizăm împreună cu API-ul pentru plugin-uri. @@ -1113,11 +1113,11 @@ Super mișto! Primul nostru plugin pentru Babel. * * * -# Operații de Transformare +# Operații de Transformare -## Vizitare (Visiting) +## Vizitare (Visiting) -### Verificare dacă un nod este de un anumit tip +### Verificare dacă un nod este de un anumit tip Dacă doriţi să verificaţi de ce tip este un anumit nod, modul preferat de a face acest lucru este: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Verificare dacă un identificator are referință +### Verificare dacă un identificator are referință ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulare +## Manipulare -### Înlocuirea unui nod +### Înlocuirea unui nod ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Înlocuirea unui nod cu mai multe noduri +### Înlocuirea unui nod cu mai multe noduri ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Notă:** Când se înlocuieşte o expresie cu mai multe noduri, acestea trebuie să fie declaraţii. Acest lucru este necesar deoarece Babel utilizează euristică pe scară largă la înlocuirea nodurilor, ceea ce înseamnă că puteţi face unele transformări destul de complexe, care altfel ar fi extrem de detaliate. -### Înlocuirea unui nod cu un șir de caractere sursă +### Înlocuirea unui nod cu un șir de caractere sursă ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Notă:** Nu este recomandat să utilizaţi acest API dacă nu aveți de a face cu șiruri de caractere sursă dinamice, altfel este mult mai eficient pentru a analiza codul în afara vizitatorului. -### Inserarea unui nod pe același nivel +### Inserarea unui nod pe același nivel ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Notă:** Acesta ar trebui să fie întotdeauna o declaraţie sau o serie de declaraţii. Aceasta utilizează aceleaşi euristici menţionate în [Înlocuirea unui nod cu mai multe noduri](#replacing-a-node-with-multiple-nodes). -### Ștergerea unui nod +### Ștergerea unui nod ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Înlocuirea unui părinte +### Înlocuirea unui părinte ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Ștergerea unui părinte +### Ștergerea unui părinte ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Domeniu (Scope) +## Domeniu (Scope) -### Verificare dacă o variabilă locală este legată +### Verificare dacă o variabilă locală este legată ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generarea unui UID +### Generarea unui UID Următorul cod va genera un identificator care nu se ciocnește cu nicio variabilă definită local. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Mutarea unei declarații de variabilă într-un domeniu părinte +### Mutarea unei declarații de variabilă într-un domeniu părinte Uneori, poate doriţi să mutați un `VariableDeclaration`, pentru a-i putea asocia o valoare. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Redenumirea unei legături și a referințelor sale +### Redenumirea unei legături și a referințelor sale ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Opțiuni de plugin +# Opțiuni de plugin Dacă doriţi să lăsați utilizatorii să particularizeze comportamentul plugin-ul vostru Babel, puteţi accepta opţiuni de plugin specifice, pe care utilizatorii le pot specifica în felul următor: @@ -1424,7 +1424,7 @@ Aceste opţiuni sunt specifice plugin-ului şi nu puteţi accesa opţiuni din al * * * -# Construirea nodurilor +# Construirea nodurilor Când scrieţi transformări veţi dori adesea să construiți unele noduri pentru a le insera în AST. Aşa cum am menţionat anterior, puteţi face acest lucru folosind metodele constructor ([builder](#builder)) din pachetul [`babel-types`](#babel-types). @@ -1535,17 +1535,17 @@ Puteţi găsi toate [definiţiile aici](https://github.com/babel/babel/tree/mast * * * -# Practici preferate +# Practici preferate > Voi lucra la această secţiune în următoarele săptămâni. -## Evitați traversarea AST pe cât posibil +## Evitați traversarea AST pe cât posibil Traversarea AST este scumpă, şi este uşor să traversați accidental AST mai mult decât este necesar. Acest lucru ar putea însemna mii daca nu zeci de mii de operaţiuni suplimentare. Babel optimizează acest lucru cât mai mult posibil, prin îmbinarea vizitatorilor împreună, dacă este posibil, pentru a face totul într-o singură traversare. -### Îmbinarea vizitatorilor ori de câte ori este posibil +### Îmbinarea vizitatorilor ori de câte ori este posibil Când scrieţi vizitatori, poate fi tentant să apelați `path.traverse` în mai multe locuri unde sunt necesare în mod logic. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Evitați traversarea când o căutare manuală este suficientă +### Evitați traversarea când o căutare manuală este suficientă De asemenea, poate fi tentant să apelați `path.traverse` atunci când căutați un anumit tip de nod. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizarea vizitatorilor imbricați +## Optimizarea vizitatorilor imbricați Atunci când aveți vizitatori imbricați, ar putea face mai mult sens să-i scrieți imbricat și în codul dumneavoastră. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Atenție la structuri imbricate +## Atenție la structuri imbricate Uneori când ne gândim la o transformare, am putea uita că structura poate fi imbricată. diff --git a/translations/ro/user-handbook.md b/translations/ro/user-handbook.md index 00884537..e6bf9ad4 100644 --- a/translations/ro/user-handbook.md +++ b/translations/ro/user-handbook.md @@ -8,42 +8,42 @@ Acest manual este disponibil și în alte limbi, a se vedea [README](/README.md) # Cuprins - * [Introducere](#introduction) - * [Inițializare Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Execuția Babel CLI (Interfața Liniei de Comandă) în cadrul unui proiect](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configurare Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Execuția codului generat de Babel](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configurare Babel (Avansată)](#configuring-babel-advanced) - * [Specificarea manuală a plugin-urilor](#manually-specifying-plugins) - * [Opțiuni de plugin](#plugin-options) - * [Personalizarea Babel în funcție de modul de lucru](#customizing-babel-based-on-environment) - * [Crearea unei presetări](#making-your-own-preset) - * [Babel şi alte instrumente](#babel-and-other-tools) - * [Instrumente de analiză statică](#static-analysis-tools) - * [Verificare cod (Linting)](#linting) - * [Stil de cod](#code-style) - * [Documentație](#documentation) - * [Framework-uri](#frameworks) - * [React](#react) - * [Editoare de text şi IDEs](#text-editors-and-ides) - * [Depanare Babel](#debugging-babel) - * [Suport Babel](#babel-support) - * [Forum Babel](#babel-forum) - * [Discuții Babel](#babel-chat) - * [Probleme Babel](#babel-issues) - * [Raportarea unei probleme Babel](#creating-an-awesome-babel-bug-report) - -# Introducere + * [Introducere](#toc-introduction) + * [Inițializare Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Execuția Babel CLI (Interfața Liniei de Comandă) în cadrul unui proiect](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configurare Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Execuția codului generat de Babel](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configurare Babel (Avansată)](#toc-configuring-babel-advanced) + * [Specificarea manuală a plugin-urilor](#toc-manually-specifying-plugins) + * [Opțiuni de plugin](#toc-plugin-options) + * [Personalizarea Babel în funcție de modul de lucru](#toc-customizing-babel-based-on-environment) + * [Crearea unei presetări](#toc-making-your-own-preset) + * [Babel şi alte instrumente](#toc-babel-and-other-tools) + * [Instrumente de analiză statică](#toc-static-analysis-tools) + * [Verificare cod (Linting)](#toc-linting) + * [Stil de cod](#toc-code-style) + * [Documentație](#toc-documentation) + * [Framework-uri](#toc-frameworks) + * [React](#toc-react) + * [Editoare de text şi IDEs](#toc-text-editors-and-ides) + * [Depanare Babel](#toc-debugging-babel) + * [Suport Babel](#toc-babel-support) + * [Forum Babel](#toc-babel-forum) + * [Discuții Babel](#toc-babel-chat) + * [Probleme Babel](#toc-babel-issues) + * [Raportarea unei probleme Babel](#toc-creating-an-awesome-babel-bug-report) + +# Introducere Babel este un compilator generic multi-scop pentru JavaScript. Folosind Babel puteţi utiliza (şi crea) următoarea generaţie de JavaScript, precum şi următoarea generaţie de instrumente JavaScript. @@ -77,7 +77,7 @@ Ecosistemul care a apărut în jurul Babel este masiv și foarte divers. Pe parc * * * -# Inițializare Babel +# Inițializare Babel Deoarece în comunitatea JavaScript există multe unelte de build, framework-uri, platforme, etc., Babel are integrări oficiale cu majoritatea dintre acestea. De la Gulp la Browserify, de la Ember la Meteor, cu siguranță există o integrare oficială. @@ -85,7 +85,7 @@ Pe parcursul acestui manual, vom acoperi doar modurile predefinite de inițializ > **Notă:** Acest ghid face referire la instrumente de linie de comandă, cum ar fi `node` şi `npm`. Înainte de a continua ar trebui să fiți confortabili cu aceste instrumente. -## `babel-cli` +## `babel-cli` Babel CLI este un mod simplu de a compila fişiere cu Babel din linia de comandă. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Execuția Babel CLI (Interfața Liniei de Comandă) în cadrul unui proiect +### Execuția Babel CLI (Interfața Liniei de Comandă) în cadrul unui proiect Deși se *poate* instala Babel CLI și la nivel global pe maşina dvs., este recomandat să-l instalaţi **local**, la nivel de proiect. @@ -171,7 +171,7 @@ npm run build Această comandă va rula Babel în acelaşi mod, ca înainte, însă folosind o instalare locală. -## `babel-register` +## `babel-register` Următoarea metoda comună de rulare Babel este prin `babel-register`. Această opţiune vă va permite să executaţi Babel doar prin cererea fişierelor, ceea ce facilitează integrarea mai bună cu setup-ul vostru. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` Dacă doar rulați cod prin intermediul `node` CLI, cel mai simplu mod de a integra Babel ar fi să utilizaţi `babel-node` CLI, care este în mare parte doar o înlocuire pentru `node` CLI. @@ -250,7 +250,7 @@ Altfel va trebui să scrieți calea către `babel-node`. > Sfat: Puteţi utiliza, de asemenea, [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` Dacă aveţi nevoie să utilizaţi Babel programatic, puteţi folosi pachetul `babel-core`. @@ -297,7 +297,7 @@ Pentru toate metodele de mai sus, `options` se referă la http://babeljs.io/docs * * * -# Configurare Babel +# Configurare Babel Poate ați observat până acum că Babel în sine nu pare să facă altceva decât să copieze fişiere JavaScript dintr-o locaţie în alta. @@ -307,7 +307,7 @@ Aceasta se întâmplă deoarece încă nu i-am specificat să facă ceva anume. Puteţi configura Babel pentru scopuri specifice prin instalarea de **plugin-uri** sau **presetări** (grupuri de plugin-uri). -## `.babelrc` +## `.babelrc` Înainte de a începe a-i spune lui Babel ce să facă. Avem nevoie să creăm un fişier de configurare. Tot ce trebuie să facem este să creăm un fişier `.babelrc` la rădăcina proiectului. Să incepem cu următoarele date: @@ -322,7 +322,7 @@ Prin intermediul acestui fișier configurăm Babel pentru a face ceea ce dorim. > **Notă:** În timp ce există și alte metode de setare a opţiunilor Babel, utilizarea fişierul `.babelrc` este cel recomandat. -## `babel-preset-es2015` +## `babel-preset-es2015` Să începem prin a instrui Babel să compileze din ES2015 (cea mai nouă versiune a standardului JavaScript, de asemenea, cunoscut și ca ES6) în ES5 (versiunea disponibilă în cele mai multe medii JavaScript astăzi). @@ -343,7 +343,7 @@ Apoi vom modifica fișierul nostru `.babelrc` pentru a include această presetar } ``` -## `babel-preset-react` +## `babel-preset-react` Setarea pentru React este la fel de simplă. Doar instalați presetarea: @@ -363,7 +363,7 @@ Apoi adăugați presetarea în fişierul `.babelrc`: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript are, de asemenea, unele propuneri care își urmează drumul lor spre standard, prin procesul TC39 (Comitetul tehnic din spatele standardul ECMAScript). @@ -401,11 +401,11 @@ Apoi o puteţi adăuga în configurarea `.babelrc`. * * * -# Execuția codului generat de Babel +# Execuția codului generat de Babel Am compilat codul cu Babel, însă nu am ajuns la finalul povestirii. -## `babel-polyfill` +## `babel-polyfill` Aproape toată sintaxa viitoare al limbajului JavaScript poate fi compilată cu Babel, dar acest lucru nu este valabil și pentru API-uri. @@ -448,7 +448,7 @@ Apoi, pur şi simplu includeți polyfill-ul în partea de sus a oricărui fişie import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` Pentru a implementa detalii ale specificațiilor ECMAScript, Babel va folosi metode de "ajutor" pentru a păstra codul generat curat. @@ -504,11 +504,11 @@ Altfel ar trebui ca ajutoarele `_classCallCheck` şi `_createClass` să le intro * * * -# Configurare Babel (Avansată) +# Configurare Babel (Avansată) Cei mai mulţi oameni vor utiliza Babel folosind doar presetările sale, însă Babel expune metode mult mai puternice și mai granulate. -## Specificarea manuală a plugin-urilor +## Specificarea manuală a plugin-urilor Presetările Babel sunt pur şi simplu colecţii de plugin-uri pre-configurate, dacă vrei să faci ceva diferit de specificarea manuală a plugin-urilor. Aceasta funcţionează aproape exact la fel ca presetările. @@ -534,7 +534,7 @@ Pentru o listă completă de plugin-uri oficiale vizitați [pagina de plugin-uri De asemenea, aruncați o privire la toate plugin-urile care au fost [construite de către comunitate](https://www.npmjs.com/search?q=babel-plugin). Dacă doriţi să învăţați cum să scrieți propriile plugin-uri, citiți [Manualul pentru Plugin-uri Babel](plugin-handbook.md). -## Opțiuni de plugin +## Opțiuni de plugin Multe plugin-uri au opţiuni pentru a le configura diferite comportamente. De exemplu, multe transformări au un mod "lejer", care renunță la unele specificații în favoarea unui cod generat mai performant și mai simplu. @@ -551,7 +551,7 @@ Pentru a adăuga opţiuni unui plug-in, faceți următoarea modificare: > Voi actualiza documentația plugin-urilor pentru a detalia fiecare opţiune, în următoarele săptămâni. [Urmăriţi-mă pentru actualizări](https://twitter.com/thejameskyle). -## Personalizarea Babel în funcție de modul de lucru +## Personalizarea Babel în funcție de modul de lucru Plugin-urile Babel rezolvă multe sarcini diferite. Multe dintre ele sunt instrumente de dezvoltare, care pot ajuta depanarea codului sau integrarea cu diverse alte instrumente. Există, de asemenea, o mulţime de plugin-uri care sunt destinate optimizării codului în producţie. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Sfat:** Dacă doriţi funcționarea atât pe platforme Unix cât şi Windows, utilizaţi [`cross-env`](https://www.npmjs.com/package/cross-env). -## Crearea unei presetări +## Crearea unei presetări Specificarea manuală a plugin-urilor? Opţiuni ale plugin-urilor? Setãri în funcție de mediu? Toate aceste configurări pot implica multă repetiţie în diferite proiecte. @@ -649,15 +649,15 @@ Apoi publicați-l pe npm şi folosiți-l ca orice altă presetare. * * * -# Babel şi alte instrumente +# Babel şi alte instrumente Babel este destul de simplu de setat, odată ce te obișnuiesti cu el, dar poate fi destul de dificil să-l integrați cu alte instrumente. Cu toate acestea, încercăm să lucrăm îndeaproape cu alte proiecte pentru a face experiența cât mai plăcută. -## Instrumente de analiză statică +## Instrumente de analiză statică Standardele mai noi aduc o mulţime de sintaxe noi limbajului şi instrumentele de analiză statică doar încep să profite de ele. -### Verificare cod (Linting) +### Verificare cod (Linting) Una dintre cele mai populare instrumente pentru linting este [ESLint](http://eslint.org), din acest motiv intreținem o integrare oficială [`babel-eslint`](https://github.com/babel/babel-eslint). @@ -703,7 +703,7 @@ $ npm run lint Pentru mai multe informaţii consultaţi documentaţia [`babel-eslint`](https://github.com/babel/babel-eslint) sau [`eslint`](http://eslint.org). -### Stil de cod +### Stil de cod JSCS este un instrument extrem de popular care duce linting-ul un pas mai departe în verificarea stilului codului. Responsabilul de bază pentru proiectele Babel şi JSCS ([@hzoo](https://github.com/hzoo)) menține o integrare oficială cu JSCS. @@ -729,19 +729,19 @@ Pentru mai multe informaţii consultaţi documentaţia [`babel-jscs`](https://gi > [WIP] --> -### Documentație +### Documentație Folosind Babel, ES2015 şi Flux puteți deduce multe despre codul vostru. Folosind [documentation.js](http://documentation.js.org) puteţi genera documentaţii detaliate pentru API-uri foarte ușor. Documentation.js foloseste Babel în spate pentru a suporta cea mai recentă sintaxă, inclusiv adnotări Flux pentru declararea tipurilor în codul dumneavoastră. -## Framework-uri +## Framework-uri Toate framework-urile JavaScript majore sunt axate acum pe alinierea API-uri lor cu viitor limbajului. Din acest motiv, s-a depus un efort considerabil în instrumente. Framework-urile au posibilitatea nu doar să folosească Babel, ci chiar să-l extindă în moduri care îmbunătățesc experiența utilizatorilor lor. -### React +### React React şi-a schimbat dramatic API-ul pentru a se alinia cu clasele ES2015 ([Citiți despre actualizarea API-ului aici](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Mai mult de atât, React se bazează pe Babel pentru a compila sintaxa JSX, renunțând la propriul instrument în favoarea Babel. Puteţi începe prin setarea pachetului `babel-preset-react` urmând [instrucţiunile de mai sus](#babel-preset-react). @@ -755,7 +755,7 @@ Cel mai notabil ar fi [`babel-plugin-react-transform`](https://github.com/gaearo > [WIP] --> -## Editoare de text şi IDEs +## Editoare de text şi IDEs Introducerea sintaxei ES2015, JSX şi Flux cu Babel poate fi de ajutor, dar dacă editorul de text nu are suport pentru acestea atunci poate fi o experienţă neplacută. Pentru acest motiv, veţi dori să vă configurați editorul de text sau IDE-ul cu un plugin Babel. @@ -772,7 +772,7 @@ Introducerea sintaxei ES2015, JSX şi Flux cu Babel poate fi de ajutor, dar dac * * * -# Suport Babel +# Suport Babel Babel are o comunitate foarte mare şi în plină creştere, iar odată cu dezvoltarea noastră vrem să ne asigurăm că oamenii au toate resursele de care au nevoie pentru a avea succes. Așadar, oferim mai multe metode pentru a obţine sprijin si ajutor. @@ -780,11 +780,11 @@ Amintiţi-vă că în toate aceste comunităţi, se aplică un [Cod de Conduită Căutăm, de asemenea, să creștem o comunitate auto-susţinută, pentru persoanele care stau prin preajmă şi îi sprijină pe alţii. Dacă cineva pune o întrebare si cunoasteți răspunsul, răpiți-vă câteva minute și dați-le o mână de ajutor. Încercați să fiți blând şi înţelegător atunci când faceți acest lucru. -## Forum Babel +## Forum Babel [Discourse](http://www.discourse.org) ne găzduiește gratuit o versiune a forum-ului lor (şi noi îi iubim pentru aceasta!). În cazul în care preferați forumurile, faceți o vizită la [discuss.babeljs.io](https://discuss.babeljs.io). -## Discuții Babel +## Discuții Babel Toată lumea iubeşte [Slack](https://slack.com). Dacă sunteţi în căutare pentru asistenţă imediată din partea comunităţii, intrați pe [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Toată lumea iubeşte [Slack](https://slack.com). Dacă sunteţi în căutare pe > [WIP] --> -## Probleme Babel +## Probleme Babel Babel utilizează un manager de probleme minunat furnizat de [Phabricator](http://phabricator.org), o platformă open source, mult mai simplă decât soluția oferită de Github. @@ -806,7 +806,7 @@ Dacă doriţi să raportați o nouă problemă: * [Autentificați-vă](https://phabricator.babeljs.io/auth/start/) sau [Creeați-vă un cont](https://phabricator.babeljs.io/auth/register/) (puteţi, de asemenea, să vă autentificați folosind GitHub, Facebook, Twitter, Google, etc.) * [Raporta-ți o problemă](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) sau [solicitați o funcționalitate nouă](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Raportarea unei probleme Babel +### Raportarea unei probleme Babel Problemele Babel pot fi uneori foarte dificil de depanat la distanţă, aşa că avem nevoie de tot ajutorul posibil. Petrecerea câtorva minute în plus pentru a crea un raport frumos și util pot ajuta în rezolvarea mult mai rapidă a problemei. diff --git a/translations/ru/README.md b/translations/ru/README.md index 769f2b6a..8f67b450 100644 --- a/translations/ru/README.md +++ b/translations/ru/README.md @@ -1,10 +1,10 @@ -# Babel Handbook +# Справочник Babel Это руководство разделено на две части: - * [User Handbook](user-handbook.md) - How to setup/configure Babel and more. - * [Plugin Handbook](plugin-handbook.md) - How to create plugins for Babel. + * [Руководство Пользователя](user-handbook.md) - Установка и настройка Babel. + * [Руководство Плагинов](plugin-handbook.md) - Создание плагинов для Babel. -> For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter. +> Оставайтесь в курсе последних обовлений - подписывайтесь в Твиттере на [@thejameskyle](https://twitter.com/thejameskyle). -Если вы читаете это не на английском языке, то вы можете наткнуться на разделы на английском, которые ещё не переведены. Если вы хотите помочь с переводом, то вы должны делать это, используя Crowdin. Прочтите, пожалуйста, [рекомендации](/CONTRIBUTING.md) для подробной информации. You will find a number of english words that are programming concepts. If these were translated to other languages there would be a lack of consistency and fluency when reading about them. In many cases you will find the literal translation followed by the english term in parenthesis `()`. For example: Abstract Syntax Trees (ASTs). \ No newline at end of file +Если вы читаете это не на английском языке, то вы можете наткнуться на разделы на английском, которые ещё не переведены. Если вы хотите помочь с переводом, то вы должны делать это, используя Crowdin. Прочтите, пожалуйста, [рекомендации](/CONTRIBUTING.md) для подробной информации. Также Вы можете встретить слова на английском, которые являются понятиями программирования. Они не были переведены умышленно, дабы сохранить удобство чтения и единство стиля. Хотя во многих случаях Вы найдете их буквальный перевод, а затем и их оригинал в скобках `()`. Например: Абстрактные Синтаксические Деревья (ASTs). \ No newline at end of file diff --git a/translations/ru/plugin-handbook.md b/translations/ru/plugin-handbook.md index a493c82d..f2c72c9b 100644 --- a/translations/ru/plugin-handbook.md +++ b/translations/ru/plugin-handbook.md @@ -1,4 +1,4 @@ -# Babel Plugin Handbook +# Руководство Плагинов Babel В этом документе описано как создавать [плагины](https://babeljs.io/docs/advanced/plugins/) для [Babel](https://babeljs.io). @@ -8,76 +8,76 @@ This handbook is available in other languages, see the [README](/README.md) for # Содержание - * [Введение](#introduction) - * [Базовые концепции](#basics) - * [Абстрактные синтаксические деревья (ASTs)](#asts) - * [Этапы работы Babel](#stages-of-babel) - * [Парсинг](#parse) - * [Лексический анализ](#lexical-analysis) - * [Синтаксический анализ](#syntactic-analysis) - * [Трансформация](#transform) - * [Генерация](#generate) - * [Обход](#traversal) - * [Посетители](#visitors) - * [Пути](#paths) - * [Пути в Посетителях](#paths-in-visitors) - * [Состояние](#state) - * [Области видимости](#scopes) - * [Привязка контекста](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Определения](#definitions) - * [Строители](#builders) - * [Валидаторы](#validators) - * [Преобразователи](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Создание вашего первого плагина Babel](#writing-your-first-babel-plugin) - * [Операции преобразования](#transformation-operations) - * [Посещение](#visiting) - * [Проверка типа узла](#check-if-a-node-is-a-certain-type) - * [Проверка, есть ли ссылка на идентификатор](#check-if-an-identifier-is-referenced) - * [Манипуляция](#manipulation) - * [Замена узла](#replacing-a-node) - * [Замена узла несколькими узлами](#replacing-a-node-with-multiple-nodes) - * [Замена узла исходной строкой](#replacing-a-node-with-a-source-string) - * [Добавление узла-потомка](#inserting-a-sibling-node) - * [Удаление узла](#removing-a-node) - * [Замена родителя](#replacing-a-parent) - * [Удаление родителя](#removing-a-parent) - * [Область видимости](#scope) - * [Проверка, привязана ли локальная переменная](#checking-if-a-local-variable-is-bound) - * [Создание UID](#generating-a-uid) - * [Отправка объявления переменной в родительскую область видимости](#pushing-a-variable-declaration-to-a-parent-scope) - * [Переименование привязки и ссылок на нее](#rename-a-binding-and-its-references) - * [Параметры плагина](#plugin-options) - * [Построение узлов](#building-nodes) - * [Лучшие практики](#best-practices) - * [Избегайте обхода AST насколько это возможно](#avoid-traversing-the-ast-as-much-as-possible) - * [Слияние посетителей, когда это возможно](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Оптимизации вложенных посетителей](#optimizing-nested-visitors) - * [Избегайте вложенных структур](#being-aware-of-nested-structures) - -# Введение + * [Введение](#toc-introduction) + * [Базовые концепции](#toc-basics) + * [Абстрактные синтаксические деревья (ASTs)](#toc-asts) + * [Этапы работы Babel](#toc-stages-of-babel) + * [Парсинг](#toc-parse) + * [Лексический анализ](#toc-lexical-analysis) + * [Синтаксический анализ](#toc-syntactic-analysis) + * [Трансформация](#toc-transform) + * [Генерация](#toc-generate) + * [Обход](#toc-traversal) + * [Посетители](#toc-visitors) + * [Пути](#toc-paths) + * [Пути в Посетителях](#toc-paths-in-visitors) + * [Состояние](#toc-state) + * [Области видимости](#toc-scopes) + * [Привязка контекста](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Определения](#toc-definitions) + * [Строители](#toc-builders) + * [Валидаторы](#toc-validators) + * [Преобразователи](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Создание вашего первого плагина Babel](#toc-writing-your-first-babel-plugin) + * [Операции преобразования](#toc-transformation-operations) + * [Посещение](#toc-visiting) + * [Проверка типа узла](#toc-check-if-a-node-is-a-certain-type) + * [Проверка, есть ли ссылка на идентификатор](#toc-check-if-an-identifier-is-referenced) + * [Манипуляция](#toc-manipulation) + * [Замена узла](#toc-replacing-a-node) + * [Замена узла несколькими узлами](#toc-replacing-a-node-with-multiple-nodes) + * [Замена узла исходной строкой](#toc-replacing-a-node-with-a-source-string) + * [Добавление узла-потомка](#toc-inserting-a-sibling-node) + * [Удаление узла](#toc-removing-a-node) + * [Замена родителя](#toc-replacing-a-parent) + * [Удаление родителя](#toc-removing-a-parent) + * [Область видимости](#toc-scope) + * [Проверка, привязана ли локальная переменная](#toc-checking-if-a-local-variable-is-bound) + * [Создание UID](#toc-generating-a-uid) + * [Отправка объявления переменной в родительскую область видимости](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Переименование привязки и ссылок на нее](#toc-rename-a-binding-and-its-references) + * [Параметры плагина](#toc-plugin-options) + * [Построение узлов](#toc-building-nodes) + * [Лучшие практики](#toc-best-practices) + * [Избегайте обхода AST насколько это возможно](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Слияние посетителей, когда это возможно](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Оптимизации вложенных посетителей](#toc-optimizing-nested-visitors) + * [Избегайте вложенных структур](#toc-being-aware-of-nested-structures) + +# Введение Babel - это многоцелевой компилятор общего назначения для JavaScript. Более того, это коллекция модулей, которая может быть использована для множества различных форм синтаксического анализа. > Статический анализ - это процесс анализа кода без запуска этого кода. (Анализ кода во время выполнения известен как динамический анализ). Цели синтаксического анализа очень разнообразны. Это может быть использовано для контроля качества кода (linting), компиляции, подсветки синтаксиса, трансформации, оптимизации, минификации и много другого. -Вы можете использовать Babel для создания множества различных инструментов, которые помогут вам стать более продуктивным и писать лучшие программы. +Вы можете использовать Babel для создания множества различных инструментов, которые помогут Вам стать более продуктивным и писать лучшие программы. -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +> ***Оставайтесь в курсе последних обовлений - подписывайтесь в Твиттере на [@thejameskyle](https://twitter.com/thejameskyle).*** * * * -# Базовые концепции +# Базовые концепции Babel - это JavaScript компилятор, точнее компилятор, преобразующий программу на одном языке в программу на другом языке (source-to-source compiler), часто называемый трянслятор. Это означает, что вы даёте Babel некоторый JavaScript код, а Babel модифицирует его, генерирует новый код и возвращает его. -## Абстрактные синтаксические деревья (ASTs) +## Абстрактные синтаксические деревья (ASTs) Каждый из этих шагов требует создания или работы с [Абстрактным синтаксическим деревом](https://en.wikipedia.org/wiki/Abstract_syntax_tree), или AST. @@ -214,15 +214,15 @@ interface Node { Эти свойства - `start`, `end`, `loc` - присутствуют в каждой отдельной ноде. -## Этапы работы Babel +## Этапы работы Babel Три основных этапа работы Babel это **парсинг**, **трансформация**, **генерация**. -### Парсинг +### Парсинг Стадия **разбора** принимает код и выводит AST. Существуют два этапа разбора в Babel: [**Лексический анализ**](https://en.wikipedia.org/wiki/Lexical_analysis) и [**Синтаксический анализ**](https://en.wikipedia.org/wiki/Parsing). -#### Лексический анализ +#### Лексический анализ Лексический анализ будет принимать строку кода и превращать его в поток **токенов**. @@ -264,21 +264,21 @@ n * n; Как узлы AST, они также имеют `start`, `end` и `loc`. -#### Синтаксический анализ +#### Синтаксический анализ Синтаксический анализ примет поток токенов и преобразует их в AST представление. Используя информацию в токенах, этот этап переформатирует их как AST, который отображает структуру кода таким образом, что облегчает работу с ним. -### Трансформация +### Трансформация Этап преобразования принимает AST и проходит через него, добавляя, обновляя, и удаляя узлы по мере прохождения. Это, безусловно, наиболее сложная часть Babel или любого компилятора. Здесь работают плагины и это будет предметом обсуждения большей части этого руководства. Поэтому мы не погружаемся слишком глубоко прямо сейчас. -### Генерация +### Генерация Этапе [генерации кода](https://en.wikipedia.org/wiki/Code_generation_(compiler)) принимает окончательное AST и преобразует его в сроку кода, так же создавая [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Генерация кода довольно проста: вы проходите через AST в глубину, строя строку, которая представляет преобразованный код. -## Обход +## Обход Когда вы хотите трансорфмировать AST вам необходимо [пройти по всему дереву](https://en.wikipedia.org/wiki/Tree_traversal) рекурсивно. @@ -330,7 +330,7 @@ n * n; Этот процесс обхода происходит в Babel на этапе преобразования. -### Посетители +### Посетители Когда мы говорим о том чтобы «пройти» к узлу, мы на самом деле имеем ввиду что мы **посещаем** его. Причина, по которой мы используем этот термин, потому что есть эта концепция [**посетителя**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Пути +### Пути AST, как правило, имеет много узлов, но как узлы связаны друг с другом? Мы могли бы иметь один гигантский изменяемый объект, которым вы манипулируете и к которому имеете полный доступ, или мы можем упростить это с **путями**. @@ -481,13 +481,13 @@ AST, как правило, имеет много узлов, но как узл } ``` -As well as tons and tons of methods related to adding, updating, moving, and removing nodes, but we'll get into those later. +А также множество методов, связанных с добавлением, обновлением, перемещением и удалением узлов, но об этом мы поговорим чуточку позже. -In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. +В некотором смысле, пути являются **активным** представлением позиции узла в дереве, а также содержат различные сведения об узле. Всякий раз эта информация обновляется, когда вызывается изменяющий дерево метод. Babel всё сделает это самостоятельно, чтобы Ваша работа с узлами была максимально легкой, и при этом, не оказывая влияния на последующие события. -#### Пути в Посетителях +#### Пути в Посетителях -When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. +Когда у вас посетитель, который имеет метод `Identifier()`, на самом деле вы посещаете сам путь вместо узла. Таким образом, Вы работаете с активным представлением узла вместо самого узла. ```js const MyVisitor = { @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### Состояние +### Состояние State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -519,7 +519,7 @@ function square(n) { } ``` -Let's write a quick hacky visitor that will rename `n` to `x`. +А теперь запустим туда коварного посетителя, который переименует `n` в `x`. ```js let paramName; @@ -539,7 +539,7 @@ const MyVisitor = { }; ``` -This might work for the above code, but we can easily break that by doing this: +Это может сработать для приведенного выше кода, но мы можем легко это прервать, вызвав: ```js function square(n) { @@ -548,7 +548,7 @@ function square(n) { n; ``` -Лучший способ справиться с этим — рекурсия. Так что давайте делать как в фильме Кристофера Нолан и положить посетителя в посетителя. +Лучший способ справиться с этим — рекурсия. Так что давайте вспомним фильм Кристофера Нолана "Начало" и положим посетителя в посетителя. ```js const updateParamNameVisitor = { @@ -572,7 +572,7 @@ const MyVisitor = { Конечно это надуманный пример, но он демонстрирует как исключить глобальное состояние из ваших посетителей. -### Области видимости +### Области видимости Далее введем понятие [**области видимости**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript имеет [лексическую область видимости](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), которая имеет структуру дерева, где блоки создают новую область видимости. @@ -588,7 +588,7 @@ function scopeOne() { } ``` -Whenever you create a reference in JavaScript, whether that be by a variable, function, class, param, import, label, etc., it belongs to the current scope. +Всякий раз, когда вы создаете ссылку в JavaScript, будь то переменной, функции, класса, параметра, импорта и т. д., она принадлежит к текущей области видимости. ```js var global = "I am in the global scope"; @@ -628,7 +628,7 @@ function scopeOne() { При написании трансформации мы хотим быть осторожными с областью видимости. Мы должны убедиться, что не поломаем существующий код в процессе изменения отдельных его частей. -We may want to add new references and make sure they don't collide with existing ones. Or maybe we just want to find where a variable is referenced. We want to be able to track these references within a given scope. +Нам может потребоваться добавить новые ссылки и убедиться, что они не пересекаются с уже существующими. Или, может быть, мы просто хотим найти, на что ссылается переменная. Другими словами, мы просто хотим иметь возможность отслеживать эти ссылки в пределах заданной области. Область видимости может быть представлена как: @@ -644,11 +644,11 @@ We may want to add new references and make sure they don't collide with existing When you create a new scope you do so by giving it a path and a parent scope. Then during the traversal process it collects all the references ("bindings") within that scope. -Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. +Как только всё это сделано, перед Вами и открываются все методы, которые можно использовать в областях видимости. Хотя как обычно, мы поговорим об этом чуточку позднее. -#### Привязка контекста +#### Привязка контекста -References all belong to a particular scope; this relationship is known as a **binding**. +Все ссылки принадлежат к определенной области; эта связь известна как **привязка**. ```js function scopeOnce() { @@ -662,7 +662,7 @@ function scopeOnce() { } ``` -A single binding looks like this: +Одиночная привязка выглядит следующим образом: ```js { @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel фактически представляет собой набор модулей. В этом разделе мы рассмотрим основные из них, объясняя, что они делают и как их использовать. > Примечание: это не замена для подробной API документации, которая вскоре будет доступна где-то в другом месте. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ babylon.parse(code, { Чтобы увидеть полный список плагинов, посетите [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Определения +### Определения Типы Babel имеют определения для каждого типа узла с информацией о том, какие свойства чему принадлежат, какие значения являются допустимыми, как построить этот узел, как узел должен быть пройден, а также псевдонимы узла. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Строители +### Строители Обратите внимание, что в приведенном выше определении для `BinaryExpression` есть поле `builder`. @@ -876,7 +876,7 @@ a * b Строители также будут проверять узлы, которые они создают и бросить ошибки если используются ненадлежащим образом. Что приводит нас к необходимости познакомиться со следующим типом методов. -### Валидаторы +### Валидаторы The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Преобразователи +### Преобразователи > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator — это генератор кода Babel. Он принимает AST и превращает его в код с sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template это еще один крошечный, но невероятно полезный модуль. Он позволяет писать строки кода с заполнителями, которые можно использовать вместо создания вручную массовых AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Создание вашего первого плагина Babel +# Создание вашего первого плагина Babel Теперь, когда вы знакомы с основами Babel, давайте свяжем это вместе с API для плагинов. @@ -1113,11 +1113,11 @@ sebmck === dork; * * * -# Операции преобразования +# Операции преобразования -## Посещение +## Посещение -### Проверка типа узла +### Проверка типа узла Если вы хотите проверить тип узла, то лучше всего сделать это следующим образом: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Проверка, есть ли ссылка на идентификатор +### Проверка, есть ли ссылка на идентификатор ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Манипуляция +## Манипуляция -### Замена узла +### Замена узла ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Замена узла несколькими узлами +### Замена узла несколькими узлами ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Примечание:** При замене выражения с несколькими узлами, они должны быть выражениями. Это потому, что Babel широко использует эвристику, при замене узлов, что означает, что вы можете сделать некоторые довольно сумасшедшие преобразования, которые в противном случае были бы чрезвычайно многословные. -### Замена узла исходной строкой +### Замена узла исходной строкой ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Примечание:** Не рекомендуется использовать этот API, если вы имеете дело с динамическим источником строк, в противном случае это более эффективно для разбора кода вне посетителя. -### Добавление узла-потомка +### Добавление узла-потомка ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Удаление узла +### Удаление узла ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Замена родителя +### Замена родителя ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Удаление родителя +### Удаление родителя ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Область видимости +## Область видимости -### Проверка, привязана ли локальная переменная +### Проверка, привязана ли локальная переменная ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Создание UID +### Создание UID Следующий код сгенерирует идентификатор, который не конфликтует ни содной из локально определенных переменных. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Отправка объявления переменной в родительскую область видимости +### Отправка объявления переменной в родительскую область видимости Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Переименование привязки и ссылок на нее +### Переименование привязки и ссылок на нее ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Параметры плагина +# Параметры плагина Если вы хотите позволить пользователям настраивать поведение вашего плагина для Babel, вы можете принимать параметры, специфичные для этого плагина, которые пользователи могут указать следующим образом: @@ -1424,7 +1424,7 @@ export default function({ types: t }) { * * * -# Построение узлов +# Построение узлов При написании преобразования часто вы хотите построить некоторые узлы для вставки в AST. Как упоминалось ранее, вы можете сделать это с помощью методов [builder](#builder) в пакете [`babel-types`](#babel-types). @@ -1466,7 +1466,7 @@ builder: ["object", "property", "computed"], > Note that sometimes there are more properties that you can customize on the node than the `builder` array contains. This is to keep the builder from having too many arguments. In these cases you need to set the properties manually. An example of this is [`ClassMethod`](https://github.com/babel/babel/blob/bbd14f88c4eea88fa584dd877759dd6b900bf35e/packages/babel-types/src/definitions/es2015.js#L238-L276). -You can see the validation for the builder arguments with the `fields` object. +Вы можете увидеть проверки для строителя аргументов с объектом `fields`. ```js fields: { @@ -1487,7 +1487,7 @@ fields: { You can see that `object` needs to be an `Expression`, `property` either needs to be an `Expression` or an `Identifier` depending on if the member expression is `computed` or not and `computed` is simply a boolean that defaults to `false`. -So we can construct a `MemberExpression` by doing the following: +Поэтому мы можем создать `MemberExpression`, выполнив следующие действия: ```js t.memberExpression( @@ -1497,21 +1497,21 @@ t.memberExpression( ); ``` -Which will result in: +Которое приведёт к: ```js object.property ``` -However, we said that `object` needed to be an `Expression` so why is `Identifier` valid? +Однако мы сказали, что `объект` должен быть `выражением`, так почему же `идентификатор` является допустимым? -Well if we look at the definition of `Identifier` we can see that it has an `aliases` property which states that it is also an expression. +Всё дело в том, что если мы посмотрим на определение `идентификатора` мы сможем увидеть, что он имеет свойство `aliases`, которое гласит, что это также является выражением. ```js aliases: ["Expression", "LVal"], ``` -So since `MemberExpression` is a type of `Expression`, we could set it as the `object` of another `MemberExpression`: +Поскольку `MemberExpression` является типом `выражения`, мы сможем установить его как `объект` другого `MemberExpression`: ```js t.memberExpression( @@ -1523,31 +1523,31 @@ t.memberExpression( ) ``` -Which will result in: +Которое приведет к: ```js member.expression.property ``` -It's very unlikely that you will ever memorize the builder method signatures for every node type. So you should take some time and understand how they are generated from the node definitions. +Скорее всего, Вам когда-либо удастся запомнить все возможные подписи метода создателя для каждого типа узла. Поэтому лучше потратить некоторое время чтобы понять, как они создаются из определений узла. Вы можете найти все актуальные [определения здесь](https://github.com/babel/babel/tree/master/packages/babel-types/src/definitions) и вы можете увидеть их [документацию здесь](https://github.com/babel/babel/blob/master/doc/ast/spec.md) * * * -# Лучшие практики +# Лучшие практики -> I'll be working on this section over the coming weeks. +> В ближайшее время этот раздел будет дополнен. -## Избегайте обхода AST насколько это возможно +## Избегайте обхода AST насколько это возможно -Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. +Обход AST - это достаточно затратное занятие, и зачастую можно сделать далеко не то, что планировалось. И в итоге повлечь тысячи, если не десятки тысяч дополнительных операций. -Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. +Babel оптимизирует это насколько, насколько это возможно, объединения посетителей вместе, чтобы сделать все в одном обходе. -### Слияние посетителей, когда это возможно +### Слияние посетителей, когда это возможно -When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. +При написании посетителей, может быть достаточно заманчиво вызвать `path.traverse` в нескольких местах, где они логически необходимым. ```js path.traverse({ @@ -1563,7 +1563,7 @@ path.traverse({ }); ``` -However, it is far better to write these as a single visitor that only gets run once. Otherwise you are traversing the same tree multiple times for no reason. +Однако, это гораздо лучше реализовать одним посетителем, который будет запускаться лишь один раз. В противном-же случае будет происходить обход одного дерева, при этом несколько раз и без причины. ```js path.traverse({ @@ -1576,9 +1576,9 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Практикуйте ручной обход -It may also be tempting to call `path.traverse` when looking for a particular node type. +При поиске конкретного типа узла так и хочется вызвать `path.traverse`. ```js const visitorOne = { @@ -1594,7 +1594,7 @@ const MyVisitor = { }; ``` -However, if you are looking for something specific and shallow, there is a good chance you can manually lookup the nodes you need without performing a costly traversal. +Однако, если Вы ищете для что-то конкретные и не глубоко, то это должно намекнуть, что в данном случае можно воспользоваться и ручной подстановкой, избегая выполнения дорогостоящих обходов различных узлов. ```js const MyVisitor = { @@ -1606,9 +1606,9 @@ const MyVisitor = { }; ``` -## Оптимизации вложенных посетителей +## Оптимизация вложенности посетителей -When you are nesting visitors, it might make sense to write them nested in your code. +Когда появляется вложенность посетителей, всё-же имеет смысл переносить эту вложенность и в Ваш код. ```js const MyVisitor = { @@ -1622,7 +1622,7 @@ const MyVisitor = { }; ``` -However, this creates a new visitor object everytime `FunctionDeclaration()` is called above, which Babel then needs to explode and validate every single time. This can be costly, so it is better to hoist the visitor up. +Однако, это создает новый объект посетителя каждый раз когда вызывается `FunctionDeclaration()`, который Babel затем должен каждый раз проверять. Это может быть достаточно затратным, так что лучше посетителя подвинуть в коде чуть выше. ```js const visitorOne = { @@ -1656,7 +1656,7 @@ const MyVisitor = { }; ``` -You can pass it in as state to the `traverse()` method and have access to it on `this` in the visitor. +То можно передать его в качестве состояния в метод `traverse()` и иметь доступ к нему через `this` в посетителе. ```js const visitorOne = { @@ -1675,11 +1675,11 @@ const MyVisitor = { }; ``` -## Избегайте вложенных структур +## Избегайте вложенных структур Иногда, когда думаете о данном преобразовании, вы можете забыть, что данная структура может быть вложенной. -For example, imagine we want to lookup the `constructor` `ClassMethod` from the `Foo` `ClassDeclaration`. +Например, Вы хотите найти `конструктор` `ClassMethod` в `Foo` `ClassDeclaration`. ```js class Foo { @@ -1707,7 +1707,7 @@ const MyVisitor = { } ``` -We are ignoring the fact that classes can be nested and using the traversal above we will hit a nested `constructor` as well: +Игнорируя то, что классы могут быть вложены, Вы будете использлвать обход выше, который также достучиться и до вложенного `конструктора`: ```js class Foo { @@ -1721,4 +1721,4 @@ class Foo { } ``` -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***Оставайтесь в курсе последних обновлений - подписывайтесь в Твиттере на [@thejameskyle](https://twitter.com/thejameskyle).*** \ No newline at end of file diff --git a/translations/ru/user-handbook.md b/translations/ru/user-handbook.md index 1f60e2a6..6183852f 100644 --- a/translations/ru/user-handbook.md +++ b/translations/ru/user-handbook.md @@ -1,63 +1,63 @@ -# Babel User Handbook +# Babel. Руководство Пользователя -This document covers everything you ever wanted to know about using [Babel](https://babeljs.io) and related tooling. +Этот документ охватывает все, что Вы когда-либо хотели знать об использовании [Babel](https://babeljs.io) и его инструментах. [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) -This handbook is available in other languages, see the [README](/README.md) for a complete list. +Это руководство также доступно и на других языках, см. [файл README](/README.md) для получения полного списка. # Содержание - * [Введение](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Введение - -Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. - -JavaScript as a language is constantly evolving, with new specs and proposals coming out with new features all the time. Using Babel will allow you to use many of these features years before they are available everywhere. - -Babel does this by compiling down JavaScript code written with the latest standards into a version that will work everywhere today. This process is known as source-to-source compiling, also known as transpiling. - -For example, Babel could transform the new ES2015 arrow function syntax from this: + * [Введение](#toc-introduction) + * [Настройка Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Запуск Babel CLI внутри проекта](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Настройка Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Запуск кода, который сконструирован в Babel](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Настройка Babel (Продвинутый уровень)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel и другие инструменты](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Отладка Babel](#toc-debugging-babel) + * [Поддержка Babel](#toc-babel-support) + * [Babel форум](#toc-babel-forum) + * [Babel чат](#toc-babel-chat) + * [Вопросы о Babel](#toc-babel-issues) + * [Как создать полезный баг репорт по Babel](#toc-creating-an-awesome-babel-bug-report) + +# Введение + +Babel — это универсальный многоцелевой компилятор для JavaScript. С его помощью можно использовать и создавать следующее поколение JavaScript, а также следующее поколения инструментов JavaScript. + +JavaScript постоянно развивается, разрастается новыми спецификациями и предложениями, новыми функции появляются буквально каждый день. Использование Babel позволит Вам реализовать многие из этих особенностей намного лет вперед, другими словами заглянуть в будущее. + +Babel делает это путем компиляции JavaScript кода, написанного по новейшим стандартам в ту версию, которая будет работать на текущей реализации. Этот процесс известен как компиляция кода. + +Например, Babel может преобразовать код, написанный по новому синтаксису реализации ES2015: ```js const square = n => n * n; ``` -Into the following: +Вот в такой: ```js const square = function square(n) { @@ -65,19 +65,19 @@ const square = function square(n) { }; ``` -However, Babel can do much more than this as Babel has support for syntax extensions such as the JSX syntax for React and Flow syntax support for static type checking. +Тем не менее, Babel может сделать гораздо больше, поскольку он имеет поддержку для синтаксиса, например React'a или Flow. -Further than that, everything in Babel is simply a plugin and anyone can go out and create their own plugins using the full power of Babel to do whatever they want. +Более того, Babel - это всего лишь плагин, и любой желающий может его использовать и создавать свои собственные плагины, используя всю мощь Babel, тем самым улучшая его. *Even further* than that, Babel is broken down into a number of core modules that anyone can use to build the next generation of JavaScript tooling. Many people do too, the ecosystem that has sprung up around Babel is massive and very diverse. Throughout this handbook I'll be covering both how built-in Babel tools work as well as some useful things from around the community. -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +> ***Оставайтесь в курсе последних обовлений - подписывайтесь в Твиттере на [@thejameskyle](https://twitter.com/thejameskyle).*** * * * -# Setting up Babel +# Настройка Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Запуск Babel CLI внутри проекта While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Настройка Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Запуск кода, который сконструирован в Babel So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Настройка Babel (Продвинутый уровень) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel и другие инструменты Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Поддержка Babel Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel форум [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel чат Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Вопросы о Babel Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Как создать полезный баг репорт по Babel Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. @@ -816,4 +816,4 @@ First, try isolating your problem. It's extremely unlikely that every part of yo * * * -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***Оставайтесь в курсе последних обовлений - подписывайтесь в Твиттере на [@thejameskyle](https://twitter.com/thejameskyle).*** \ No newline at end of file diff --git a/translations/sr/plugin-handbook.md b/translations/sr/plugin-handbook.md index 53d9623d..0b75d121 100644 --- a/translations/sr/plugin-handbook.md +++ b/translations/sr/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Sadržaj - * [Uvod](#introduction) - * [Osnove](#basics) - * [AST strukture](#asts) - * [Stanja pri kompajliranja (Stages of Babel)](#stages-of-babel) - * [Parsiranje](#parse) - * [Leksička analiza (Lexical Analysis)](#lexical-analysis) - * [Analiza sintakse (Syntactic Analysis)](#syntactic-analysis) - * [Transformisanje (Transform)](#transform) - * [Generisanje (Generate)](#generate) - * [Prolazak (Traversal)](#traversal) - * [Posetioci (Visitors)](#visitors) - * [Putanje (paths)](#paths) - * [Putanje u "posetiocima"](#paths-in-visitors) - * [Stanje (state)](#state) - * [Domeni (scopes)](#scopes) - * [Vezivanje (bindings)](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Defincije](#definitions) - * [Gradioci (Builders)](#builders) - * [Validatori](#validators) - * [Konvertori](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Kreiranje vašeg prvog Babel plugina](#writing-your-first-babel-plugin) - * [Operacije transformisanja](#transformation-operations) - * [Posećivanje (visiting)](#visiting) - * [Proverite da li je čvor određenog tipa](#check-if-a-node-is-a-certain-type) - * [Proverite da li neko referencira identifikator](#check-if-an-identifier-is-referenced) - * [Manipulacija](#manipulation) - * [Zamena čvora](#replacing-a-node) - * [Zamenjivanje čvora sa više čvorova](#replacing-a-node-with-multiple-nodes) - * [Zamenjivanje čvorova sa stringom koda](#replacing-a-node-with-a-source-string) - * [Umetanje susednih čvorova](#inserting-a-sibling-node) - * [Uklanjanje čvora](#removing-a-node) - * [Zamena nadčvora (parent)](#replacing-a-parent) - * [Uklanjanje nadčvora (parent)](#removing-a-parent) - * [Domen](#scope) - * [Proveravanje da li je lokalna promenljiva "vezana" (bounded)](#checking-if-a-local-variable-is-bound) - * [Generisanje UID-a](#generating-a-uid) - * [Pomeranje deklaracije promenljive na naddomen (parent scope)](#pushing-a-variable-declaration-to-a-parent-scope) - * [Promena imena "vezivanja" i njegovih referenci](#rename-a-binding-and-its-references) - * [Plagin opcije](#plugin-options) - * [Kreiranje čvorova](#building-nodes) - * [Praktični saveti](#best-practices) - * [Izbegavajte prolazak kroz AST što je više moguće](#avoid-traversing-the-ast-as-much-as-possible) - * [Spajanje "posetioca" kad je to moguće](#merge-visitors-whenever-possible) - * [Izbegavajte prolaske kada može da se upotrebi ručno prolaženje (kroz čvorove)](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizacija ugnežđenih "posetioca"](#optimizing-nested-visitors) - * [Obratite pažnju na ugnežđene strukture](#being-aware-of-nested-structures) - -# Uvod + * [Uvod](#toc-introduction) + * [Osnove](#toc-basics) + * [AST strukture](#toc-asts) + * [Stanja pri kompajliranja (Stages of Babel)](#toc-stages-of-babel) + * [Parsiranje](#toc-parse) + * [Leksička analiza (Lexical Analysis)](#toc-lexical-analysis) + * [Analiza sintakse (Syntactic Analysis)](#toc-syntactic-analysis) + * [Transformisanje (Transform)](#toc-transform) + * [Generisanje (Generate)](#toc-generate) + * [Prolazak (Traversal)](#toc-traversal) + * [Posetioci (Visitors)](#toc-visitors) + * [Putanje (paths)](#toc-paths) + * [Putanje u "posetiocima"](#toc-paths-in-visitors) + * [Stanje (state)](#toc-state) + * [Domeni (scopes)](#toc-scopes) + * [Vezivanje (bindings)](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Defincije](#toc-definitions) + * [Gradioci (Builders)](#toc-builders) + * [Validatori](#toc-validators) + * [Konvertori](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Kreiranje vašeg prvog Babel plugina](#toc-writing-your-first-babel-plugin) + * [Operacije transformisanja](#toc-transformation-operations) + * [Posećivanje (visiting)](#toc-visiting) + * [Proverite da li je čvor određenog tipa](#toc-check-if-a-node-is-a-certain-type) + * [Proverite da li neko referencira identifikator](#toc-check-if-an-identifier-is-referenced) + * [Manipulacija](#toc-manipulation) + * [Zamena čvora](#toc-replacing-a-node) + * [Zamenjivanje čvora sa više čvorova](#toc-replacing-a-node-with-multiple-nodes) + * [Zamenjivanje čvorova sa stringom koda](#toc-replacing-a-node-with-a-source-string) + * [Umetanje susednih čvorova](#toc-inserting-a-sibling-node) + * [Uklanjanje čvora](#toc-removing-a-node) + * [Zamena nadčvora (parent)](#toc-replacing-a-parent) + * [Uklanjanje nadčvora (parent)](#toc-removing-a-parent) + * [Domen](#toc-scope) + * [Proveravanje da li je lokalna promenljiva "vezana" (bounded)](#toc-checking-if-a-local-variable-is-bound) + * [Generisanje UID-a](#toc-generating-a-uid) + * [Pomeranje deklaracije promenljive na naddomen (parent scope)](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Promena imena "vezivanja" i njegovih referenci](#toc-rename-a-binding-and-its-references) + * [Plagin opcije](#toc-plugin-options) + * [Kreiranje čvorova](#toc-building-nodes) + * [Praktični saveti](#toc-best-practices) + * [Izbegavajte prolazak kroz AST što je više moguće](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Spajanje "posetioca" kad je to moguće](#toc-merge-visitors-whenever-possible) + * [Izbegavajte prolaske kada može da se upotrebi ručno prolaženje (kroz čvorove)](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizacija ugnežđenih "posetioca"](#toc-optimizing-nested-visitors) + * [Obratite pažnju na ugnežđene strukture](#toc-being-aware-of-nested-structures) + +# Uvod Babel je generički višenamenski kompajler za JavaScript. Sastoji se od kolekcije modula koji se mogu koristiti u različitim vidovima statičke analize koda. @@ -73,11 +73,11 @@ Uz pomoć Babel-a možete napisati mnoštvo različitih tipova alatki koje mogu * * * -# Osnove +# Osnove Babel je JavaScript kompajler, tačnije kompajler iz koda u kod, što se najčešće naziva "transpiler". Drugim rečima, Babel može da modifikuje i da generiše potpuno novi kod na osnovu vašeg koda. -## AST strukture +## AST strukture Svaki od koraka pri kompajliranju uključuje kreiranje ili korišćenje apstraktnog sintaksnog stabla [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) tj. AST. @@ -214,15 +214,15 @@ Za svaki čvor koji je generisan Babelom koriste se dodatni podaci koji sadrže Polja (properties) `start`, `end`, `loc` se mogu naći u svakom pojedinačnom čvoru. -## Stanja pri kompajliranja (Stages of Babel) +## Stanja pri kompajliranja (Stages of Babel) Tri osnovna stanja kroz koje Babel prolazi su **parsiranje**, **transformisanje**, **generisanje**. -### Parsiranje +### Parsiranje U fazi **parsiranja**, kod se pretvara u AST strukturu. Parsiranje čine dve faze: [**Leksička analiza**](https://en.wikipedia.org/wiki/Lexical_analysis) (Lexical Analysis) i [**Analiza sintakse**](https://en.wikipedia.org/wiki/Parsing) (Syntactic Analysis). -#### Leksička analiza (Lexical Analysis) +#### Leksička analiza (Lexical Analysis) U leksičkoj analizi delić koda se pretvara u niz **tokena**. @@ -264,21 +264,21 @@ U svakom `tipu` imamo skup polja (properties) koje opisuju dati token: Kao i u elementima AST strukture i ovde imamo polja `start`, `end`, and `loc`. -#### Analiza sintakse (Syntactic Analysis) +#### Analiza sintakse (Syntactic Analysis) Analiza sintakse koristi niz tokena i pretvara ih u AST formu. U ovoj fazi tokeni su, na osnovu informacija koje nose, restruktuirani u formu AST-a. Ovakva reprezentacija strukture koda je daleko jednostavnija za dalje procesiranje. -### Transformisanje (Transform) +### Transformisanje (Transform) U stanju [transformisanja](https://en.wikipedia.org/wiki/Program_transformation) Babel prolazi kroz čvorove AST strukture i pri tom kreira nove, briše ili modifikuje postojeće čvorove. Ovo je daleko najsloženiji deo kroz koji prolazi bilo Babel bilo koji drugi kompajler. Plaginovi svoje procese obavljaju u ovom stanju pa će ovo stanje biti glavna tema u većem delu ovog priručnika. Zbog toga nećemo ulaziti duboko u detalje za sad. -### Generisanje (Generate) +### Generisanje (Generate) Stanje [generisanje koda](https://en.wikipedia.org/wiki/Code_generation_(compiler)) koristi AST generisan u prethodnom stanju i na osnovu njega generiše kod i kreira [mapu koda](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) (source map). Generisanje koda je prilično jednostavan proces: prolazi se kroz AST strukturu i ispišu stringovi koji predstavljaju transformisani kod. -## Prolazak (Traversal) +## Prolazak (Traversal) Pri transformaciji AST strukture potrebno je rekurzivno [proći kroz stablo](https://en.wikipedia.org/wiki/Tree_traversal) kojim je predstavljen. @@ -330,7 +330,7 @@ Struktura `BinaryExpression` ima polja `operator`, a `left`, i a `right`. Polje Opisani proces prolaska se desava u stanju transformisanja (transform stage). -### Posetioci (Visitors) +### Posetioci (Visitors) Kada govorimo o "prolasku" kroz čvor, zapravo mislimo na njihovo **podsećivanje**. Ovaj termin se korisiti zato što postoji koncept [**visitora**](https://en.wikipedia.org/wiki/Visitor_pattern) (visitor). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Putanje (paths) +### Putanje (paths) Generalno, AST se sastoji od više čvorova. Postavlja se pitanje kako su oni međusobno povezani? Možemo da imamo jeda ogroman promenljivi objekat sa kojim manipulišemo i imati potpun pristup ka svakom njegovom delu ili možemo da pojednostavimo ovo manipulisanje korišćenjem **putanja**. @@ -485,7 +485,7 @@ Kasnije ćemo razmotriti veliki broj metoda vezanih za dodavanje, modifikovanje, Na neki način, "putanje" su **reaktivne** reprezentacije položaja čvorova unutar stabla kao i različite informacije o čvoru. Pozivanjem metoda koje modifikuju stablo se ažuriraju informacije o njegovoj strukturi. Sve ovo vam omogućava Babel kako bi korišćenje čvorova bilo što olakšano i nezavisno od stanja u kojima se nalaze. -#### Putanje u "posetiocima" +#### Putanje u "posetiocima" Kad imamo "posetioca" koji ima `Identifier()` metod, u stanju smo da radimo sa putanjom umesto sa čvorom. Na ovaj način možemo da koristimo reaktivnu reprezentaciju čvora umesto samog čvora. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### Stanje (state) +### Stanje (state) Stanje je neprijatelj AST transformacija. Stanje će vas uvek napadati i vaše pretpostavke o stanju će skoro uvek biti pogrešne tako što će se pojavljivati sintakse koda koje niste očekivali. @@ -572,7 +572,7 @@ const MyVisitor = { Iako je ovo specifičan primer, on demonstira kako da izbegnemo korišćenje globalog stanja u vašem "posetiocu". -### Domeni (scopes) +### Domeni (scopes) Uvedimo sad koncept [**domena**](https://en.wikipedia.org/wiki/Scope_(computer_science)) (scope). JavaScript koristi [leksički domen](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping) (lexical scoping) - strukturu stabla u kojoj svaki blok koda kreira novi domen. @@ -646,7 +646,7 @@ Novi domen kreiramo tako da mu dodeljujemo putanju i nadređeni domen (parent sc Nakon toka, na domen možemo da primenumo veliko broj metoda. Njih ćemo razmotriti kasnije. -#### Vezivanje (bindings) +#### Vezivanje (bindings) Reference pripadaju određenom domenu; ovu relaciju nazivamo **vezivanje** (binding). @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel u osnovi čini kolekciju modula. U ovom odeljku ćemo pomenuti one koji su najbitniji, objašnjavajući šta oni rade i kako se koriste. > Napomena: Ovaj dokument ne zamenjuje detaljnu API dokumentaciju koja će uskoro biti dostupna na drugom mestu. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon je parser koji se koristi u Babelu. Ovaj modul je nastao kao "ogranak" (fork) projekta Acorn, veoma je brz, jednostavan za korišćenje, ima arhitekturu "plugina" koja je upotrebljiva za nestandardne potrebe (kao i za buduće standarde). @@ -753,7 +753,7 @@ Kako se Babylon sagrađen na arhitekturi baziranoj na plaginovima, postoji `plug Kompletna lista plaginova je data u [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) Babel Traverse modul procesira ukupno stanje stabla i odgovoran je za zamene, uklanjanja i dodavanje čvorova. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types podseća na Loadas biblioteku primenjenu na AST čvorove. Biblioteka sadrži metode za kreiranje, validaciju i konverziju AST čvorova. Korisna je za pročišćavanje logike u AST strukturi korišćenjem dobro osmišljenih pomoćnih metoda. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Defincije +### Defincije Babel Types sadrži definicije za svaki pojedinačni tip čvora, sa informacija koje se strukture podataka koriste u njima, koje su validne vrednosti unutar strukture, kako se kreiraju određeni čvorovi, kako se prolazi kroz čvorove i koji su alijasi (aliases) za čvorove. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Gradioci (Builders) +### Gradioci (Builders) Primetićete da gornja definicija `BinaryExpression` ima polje `builder`. @@ -876,7 +876,7 @@ a * b "Gradioci", takođe, validiraju čvorove koje kreiraju i bacaju greške sa opisom ako nisu korišćeni na pravi način. Ovo nas vodi u sledeći tip metoda. -### Validatori +### Validatori Definicija `BinaryExpression`, takođe, uključuje informacije o `poljima` čvora i kako se validiraju. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Konvertori +### Konvertori > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator je generator koda u okviru Babela. Njegova uloga je da pretvori AST strukturu u kod sa mapama koda (sourcemaps). @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template je sledeći mali, ali izuzetno koristan modul. On omogućava pisanje stringova koda sa "mestima za zamene" (placeholders) koje možemo koristiti umesto ručnog kreiranja ogromne AST strukture. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Kreiranje vašeg prvog Babel plugina +# Kreiranje vašeg prvog Babel plugina Nakon što smo se upoznali sa osnova Babela, pokušajmo da stečeno znanje iskoristimu u radu sa plugin API-ijem. @@ -1113,11 +1113,11 @@ Neviđeno! Naš prvi Babel plagin. * * * -# Operacije transformisanja +# Operacije transformisanja -## Posećivanje (visiting) +## Posećivanje (visiting) -### Proverite da li je čvor određenog tipa +### Proverite da li je čvor određenog tipa Ako želite da proverite koga je tipa dati čvor, najbolji način da to uradite je: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Proverite da li neko referencira identifikator +### Proverite da li neko referencira identifikator ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulacija +## Manipulacija -### Zamena čvora +### Zamena čvora ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Zamenjivanje čvora sa više čvorova +### Zamenjivanje čvora sa više čvorova ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Napomena:** Kad zamenjujete izraz sa više čvorovan, oni moraju biti izrazi (statements). Razlog za ovo je što Babel intenzivno koristi heuristiku kada zamenjuje čvorove, što znači da možete da uradite prilično neobične transformacije koje bi u suprotnom tražile jako veliko broj linija koda. -### Zamenjivanje čvorova sa stringom koda +### Zamenjivanje čvorova sa stringom koda ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Napomena:** Nije preporučljivo koristit ovaj API ukoliko ne radite sa izvorom dinamičkih stringova. U suprotnom, mnogo je efikasnije da se kod parsira izvan "posetioca". -### Umetanje susednih čvorova +### Umetanje susednih čvorova ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Napomena:** Ovo uvek treba da bude izraz ili niz izraza. Ovde se koristi ista heuristika kao i u [Zamenjivanje čvora sa više čvorova](#replacing-a-node-with-multiple-nodes). -### Uklanjanje čvora +### Uklanjanje čvora ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Zamena nadčvora (parent) +### Zamena nadčvora (parent) ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Uklanjanje nadčvora (parent) +### Uklanjanje nadčvora (parent) ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Domen +## Domen -### Proveravanje da li je lokalna promenljiva "vezana" (bounded) +### Proveravanje da li je lokalna promenljiva "vezana" (bounded) ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generisanje UID-a +### Generisanje UID-a Ovo će da generiše identifikator koji se ne sudara sa identifikatorom ni jedne lokalno definisane promenljive. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pomeranje deklaracije promenljive na naddomen (parent scope) +### Pomeranje deklaracije promenljive na naddomen (parent scope) Ponekad je potrebno da pomerite `VariableDeclaration` tako da datoj promenljivoj možete da pridružite vrednost. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Promena imena "vezivanja" i njegovih referenci +### Promena imena "vezivanja" i njegovih referenci ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plagin opcije +# Plagin opcije Ako želite da omogućite vašim korisnicima da menjaju ponašanje vaših Babel plaginova možete da prihvatite posebne opcije plagina koje korisnik može da specificira na sledeći način: @@ -1424,7 +1424,7 @@ Ove opcije su dodeljene samo pojedinačnim plaginovima i nije im moguće pristup * * * -# Kreiranje čvorova +# Kreiranje čvorova Pri pisanju transformacija često je potrebno da dodamo nove čvorove u AST stablo. Kao što je prethodno rečeno, ovo je moguće izvesti korišćenjem metoda [gradioca](#builder) (builders) definisanih u [`babel-types`](#babel-types) paketu. @@ -1535,17 +1535,17 @@ Definicije čvorova možete da nađete [ovde](https://github.com/babel/babel/tre * * * -# Praktični saveti +# Praktični saveti > O toku sledećih sedmica ću proširiti sadržaj ovog odeljka. -## Izbegavajte prolazak kroz AST što je više moguće +## Izbegavajte prolazak kroz AST što je više moguće Prolaženje kroz AST je veoma skupa operacija, i lako se dešava da slučajno prolazite kroz AST više nego što je pogrebno. To dovodi do izvršavanja hiljade ako ne i desetine hiljada dodatnih operacija. Babel ovo optimizuje koliko god može, spajajući "posetioce" zajedno kad je to moguće u cilju da se ceo posao završi u samo jednom prolasku. -### Spajanje "posetioca" kad je to moguće +### Spajanje "posetioca" kad je to moguće Kad pišemo posetioce, može biti pogodno da se `path.traverse` poziva na više mesta gde to logika problema nalaže. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Izbegavajte prolaske kada može da se upotrebi ručno prolaženje (kroz čvorove) +### Izbegavajte prolaske kada može da se upotrebi ručno prolaženje (kroz čvorove) Kada tražimo koga je tipa određeni čvor, može doći do pozivanja metoda `path.traverse`. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizacija ugnežđenih "posetioca" +## Optimizacija ugnežđenih "posetioca" Kada je potrebno da koristite ugnežđene "posetioce", ima smisla da ih napišete ugnežđeno u vašem kodu. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Obratite pažnju na ugnežđene strukture +## Obratite pažnju na ugnežđene strukture Ponekad kad razmišljamo o datim transformacijama, možemo da zaboravimo da date strukture mogu biti ugnežđene. diff --git a/translations/sr/user-handbook.md b/translations/sr/user-handbook.md index 25861c2a..de9dddaf 100644 --- a/translations/sr/user-handbook.md +++ b/translations/sr/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Sadržaj - * [Uvod](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Uvod + * [Uvod](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Uvod Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/sv-SE/README.md b/translations/sv-SE/README.md index c09f34b5..0da97c85 100644 --- a/translations/sv-SE/README.md +++ b/translations/sv-SE/README.md @@ -1,10 +1,10 @@ -# Babel Handbook +# Babelhandbok -This handbook is divided into two parts: +Denna handbok är indelad i två delar: - * [User Handbook](user-handbook.md) - How to setup/configure Babel and more. - * [Plugin Handbook](plugin-handbook.md) - How to create plugins for Babel. + * [Användarhandbok](user-handbook.md) - installation/konfigurering av Babel och mycket mer. + * [Pluginhandbok](plugin-handbook.md) - hur man skapar plugins för Babel. -> For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter. +> För framtida uppdateringar, följ [@thejameskyle](https://twitter.com/thejameskyle) på Twitter. -If you are reading a non-english translation of this handbook you may still find english sections that have not yet been translated. If you would like to contribute to one of the translations you must do so through Crowdin. Please read the [contributing guidelines](/CONTRIBUTING.md) for more information. You will find a number of english words that are programming concepts. If these were translated to other languages there would be a lack of consistency and fluency when reading about them. In many cases you will find the literal translation followed by the english term in parenthesis `()`. For example: Abstract Syntax Trees (ASTs). \ No newline at end of file +Om du läser en icke-engelsk översättning av denna handbok kan du fortfarande hitta sektioner som ännu inte har översatts. Om du vill bidra till en av översättningarna måste du göra det genom Crowdin. Läs den [riktlinjerna för att bidra](/CONTRIBUTING.md) för mer information. Här hittar du ett antal engelska ord som är programmeringsbegrepp. Om dessa översattes till andra språk skulle det finnas en brist på konsekvens och flyt när man läser om dem. I många fall hittar du den bokstavliga översättningen följt av den engelska termen i parentes `()`. Till exempel: abstrakt syntaxträd (ASTs). \ No newline at end of file diff --git a/translations/sv-SE/plugin-handbook.md b/translations/sv-SE/plugin-handbook.md index 1ae48634..d0418906 100644 --- a/translations/sv-SE/plugin-handbook.md +++ b/translations/sv-SE/plugin-handbook.md @@ -1,87 +1,87 @@ -# Babel Plugin Handbook +# Babel Plugin handbok -This document covers how to create [Babel](https://babeljs.io) [plugins](https://babeljs.io/docs/advanced/plugins/). +Det här dokumentet tar upp hur man skapar [Babel](https://babeljs.io) [plugins](https://babeljs.io/docs/advanced/plugins/). [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) -This handbook is available in other languages, see the [README](/README.md) for a complete list. - -# Table of Contents - - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction - -Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. - -> Static analysis is the process of analyzing code without executing it. (Analysis of code while executing it is known as dynamic analysis). The purpose of static analysis varies greatly. It can be used for linting, compiling, code highlighting, code transformation, optimization, minification, and much more. - -You can use Babel to build many different types of tools that can help you be more productive and write better programs. - -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +Handboken finns på andra språk, se [README](/README.md) för en komplett lista. + +# Innehållsförteckning + + * [Introduktion](#toc-introduction) + * [Grunderna](#toc-basics) + * [ASTs](#toc-asts) + * [Stadier av Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexikalisk analys](#toc-lexical-analysis) + * [Syntaktisk analys](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduktion + +Babel är en generisk multi-purpose kompilator för JavaScript. Utöver detta är Babel en samling av moduler som kan användas till många olika former av statisk analys. + +> Med statisk analys innebär att analysera kod utan att köra den. (Analys av koden vid körning kallas dynamisk analys). Syftet med statisk analys varierar stort. Det kan användas för att "linta", kompilera, "kod-hightligt", kodtransformering, optimisering, minimering och mycket mer. + +Med Babel kan du bygga olika typer av verktyg som hjälper dig att bli mer produktiv och skriva bättre program. + +> ***För framtida uppdateringar, Följ [@thejameskyle](https://twitter.com/thejameskyle) på Twitter.*** * * * -# Basics +# Grunderna -Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. +Babel är en JavaScript kompilator, särskilt en källa-till-källa kompilator, ofta kallad en "transpiler". Detta innebär att du ger Babel JavaScript-kod, där koden ändras och genererar den nya koden som skickas tillbaka. -## ASTs +## ASTs -Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. +Alla dessa steg innebär att skapa eller arbeta med ett [Abstrakt Syntax träd](https://en.wikipedia.org/wiki/Abstract_syntax_tree) eller AST. -> Babel uses an AST modified from [ESTree](https://github.com/estree/estree), with the core spec located [here](https://github.com/babel/babel/blob/master/doc/ast/spec.md). +> Babel använder en AST modifierad från [ESTree](https://github.com/estree/estree), där kodspecifikationen kan hittas [här](https://github.com/babel/babel/blob/master/doc/ast/spec.md). ```js function square(n) { @@ -89,9 +89,9 @@ function square(n) { } ``` -> Check out [AST Explorer](http://astexplorer.net/) to get a better sense of the AST nodes. [Here](http://astexplorer.net/#/Z1exs6BWMq) is a link to it with the example code above pasted in. +> Kolla in [AST Explorer](http://astexplorer.net/) för att få en bättre känsla för AST-noder. [Här](http://astexplorer.net/#/Z1exs6BWMq) är en länk till det där exempelkoden ovan klistrats in i. -This same program can be represented as a list like this: +Samma program kan representeras som en lista så här: ```md - FunctionDeclaration: @@ -116,7 +116,7 @@ This same program can be represented as a list like this: - name: n ``` -Or as a JavaScript Object like this: +Eller som JavaScript-objekt: ```js { @@ -150,7 +150,7 @@ Or as a JavaScript Object like this: } ``` -You'll notice that each level of the AST has a similar structure: +Du kommer att märka att varje nivå av AST har en liknande struktur: ```js { @@ -177,11 +177,11 @@ You'll notice that each level of the AST has a similar structure: } ``` -> Note: Some properties have been removed for simplicity. +> Obs: Vissa egenskaper har tagits bort för enkelhet. -Each of these are known as a **Node**. An AST can be made up of a single Node, or hundreds if not thousands of Nodes. Together they are able to describe the syntax of a program that can be used for static analysis. +Alla dessa är kända som en **nod**. En AST kan bestå av en enda nod, eller hundratals om inte tusentals noder. Tillsammans kan de beskriva syntaxen för ett program som kan användas för statisk analys. -Every Node has this interface: +Varje nod har detta gränssnitt: ```typescript interface Node { @@ -189,9 +189,9 @@ interface Node { } ``` -The `type` field is a string representing the type of Node the object is (ie. `"FunctionDeclaration"`, `"Identifier"`, or `"BinaryExpression"`). Each type of Node defines an additional set of properties that describe that particular node type. +Fältet `typ` är en sträng som representerar den typ av nod objektet är (dvs. `"FunctionDeclaration"`, `"Identifier"`, eller `"BinaryExpression"`). Varje typ av nod definierar ytterligare en uppsättning egenskaper som beskriver den särskilda nodtypen. -There are additional properties on every Node that Babel generates which describe the position of the Node in the original source code. +Det finns ytterligare egenskaper på varje nod som Babel genererar vilket beskriver nodens position i den ursprungliga källkoden. ```js { @@ -212,17 +212,17 @@ There are additional properties on every Node that Babel generates which describ } ``` -These properties `start`, `end`, `loc`, appear in every single Node. +Dessa egenskaper `start`, `end`, `loc`, visas i varje enskild nod. -## Stages of Babel +## Stadier av Babel -The three primary stages of Babel are **parse**, **transform**, **generate**. +De tre primära stadierna av Babel är **parse**, **transform** och **generate**. -### Parse +### Parse -The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). +**Parse** tar koden och genererar en AST. Det finns två faser av satsanalysering i Babel: [**Lexikal analys**](https://en.wikipedia.org/wiki/Lexical_analysis) och [**Syntaktisk analys**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexikalisk analys Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntaktisk analys Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. @@ -1721,4 +1721,4 @@ class Foo { } ``` -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***För framtida uppdateringar, följ [@thejameskyle](https://twitter.com/thejameskyle) på Twitter.*** \ No newline at end of file diff --git a/translations/sv-SE/user-handbook.md b/translations/sv-SE/user-handbook.md index c269bd9c..35af581e 100644 --- a/translations/sv-SE/user-handbook.md +++ b/translations/sv-SE/user-handbook.md @@ -4,46 +4,46 @@ This document covers everything you ever wanted to know about using [Babel](http [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) -This handbook is available in other languages, see the [README](/README.md) for a complete list. - -# Table of Contents - - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction +Handboken finns på andra språk, se [README](/README.md) för en komplett lista. + +# Innehållsförteckning + + * [Introduktion](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduktion Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -73,11 +73,11 @@ Further than that, everything in Babel is simply a plugin and anyone can go out Many people do too, the ecosystem that has sprung up around Babel is massive and very diverse. Throughout this handbook I'll be covering both how built-in Babel tools work as well as some useful things from around the community. -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** +> ***För framtida uppdateringar, följ [@thejameskyle](https://twitter.com/thejameskyle) på Twitter.*** * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. @@ -816,4 +816,4 @@ First, try isolating your problem. It's extremely unlikely that every part of yo * * * -> ***For future updates, follow [@thejameskyle](https://twitter.com/thejameskyle) on Twitter.*** \ No newline at end of file +> ***För framtida uppdateringar, följ [@thejameskyle](https://twitter.com/thejameskyle) på Twitter.*** \ No newline at end of file diff --git a/translations/tr/README.md b/translations/tr/README.md index ed3b6091..3c32d0d8 100644 --- a/translations/tr/README.md +++ b/translations/tr/README.md @@ -7,4 +7,4 @@ Bu el kitabı iki bölümden oluşur: > Gelecek güncellemeler için [@thejameskyle](https://twitter.com/thejameskyle)'i Twitter'dan takip edin. -Eğer bu el kitabının İngilizce olmayan bir çevirisini okuyorsanız, halen çevrilmemiş bölümler görebilirsiniz. Eğer bu çevirilerden birine katkıda bulunmak istiyorsanız, bunu Crowdin aracılığıyla yapmalısınız. Lütfen daha fazla bilgi için [katkıda bulunma rehberi](/CONTRIBUTING.md)ne göz atın. Bazı programlama konseptlerinin İngilizce olarak yazıldığını göreceksiniz. If these were translated to other languages there would be a lack of consistency and fluency when reading about them. In many cases you will find the literal translation followed by the english term in parenthesis `()`. For example: Abstract Syntax Trees (ASTs). \ No newline at end of file +Eğer bu el kitabının İngilizce olmayan bir çevirisini okuyorsanız, halen çevrilmemiş bölümler görebilirsiniz. Eğer bu çevirilerden birine katkıda bulunmak istiyorsanız, bunu Crowdin aracılığıyla yapmalısınız. Lütfen daha fazla bilgi için [katkıda bulunma rehberi](/CONTRIBUTING.md)ne göz atın. Bazı programlama konseptlerinin İngilizce olarak yazıldığını göreceksiniz. Eğer bunlar diğer dillere çevirilir ise okumada tutarlılık ve akıcılık eksikliği olacaktır. Birçok durumda parantez içindeki ingilizce terimin edebi çevirisini bulacaksınız.`()`. Örneğin: Soyut Sözdizimi Ağaçları (ASTs). \ No newline at end of file diff --git a/translations/tr/plugin-handbook.md b/translations/tr/plugin-handbook.md index 751bcf09..49d19e99 100644 --- a/translations/tr/plugin-handbook.md +++ b/translations/tr/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/tr/user-handbook.md b/translations/tr/user-handbook.md index 0c62b61e..5f6f6106 100644 --- a/translations/tr/user-handbook.md +++ b/translations/tr/user-handbook.md @@ -1,49 +1,49 @@ -# Babel User Handbook +# Babel Kullanıcı Elkitabı -This document covers everything you ever wanted to know about using [Babel](https://babeljs.io) and related tooling. +Bu belge [Babel](https://babeljs.io) ve ilgili araçları ile ilgili bilmek isteyeceğiniz herşeyi kapsar. [![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/) -This handbook is available in other languages, see the [README](/README.md) for a complete list. - -# Table of Contents - - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction +Bu kitabın diğer dillere tercümeside mevcuttur.Tüm liste için [README](/README.md)'ye bakın. + +# İçindekiler + + * [Giriş](#toc-introduction) + * [Babel Kurulumu](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Proje içinde Babel CLI çalıştırmak](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Babel Yapılandırması](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Üretilen kodu çalıştırma](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Babel (Gelişmiş) yapılandırma](#toc-configuring-babel-advanced) + * [Eklentileri el ile belirtme](#toc-manually-specifying-plugins) + * [Eklenti seçenekleri](#toc-plugin-options) + * [Ortama göre Babel'i özelleştirme](#toc-customizing-babel-based-on-environment) + * [Kendi önceden belirlenmiş ayarlarınızı yapmak](#toc-making-your-own-preset) + * [Babil ve diğer araçlar](#toc-babel-and-other-tools) + * [Statik analiz araçları](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Kod stili](#toc-code-style) + * [Dökümantasyon](#toc-documentation) + * [Frameworkler](#toc-frameworks) + * [React](#toc-react) + * [Metin düzenleyicileri ve IDE'ler](#toc-text-editors-and-ides) + * [Babel Hata Ayıklama](#toc-debugging-babel) + * [Babel destek](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel sohbet](#toc-babel-chat) + * [Babel sorunları](#toc-babel-issues) + * [Harika bir Babil hata raporu oluşturma](#toc-creating-an-awesome-babel-bug-report) + +# Giriş Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Babel Kurulumu Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Proje içinde Babel CLI çalıştırmak While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Babel Yapılandırması You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Üretilen kodu çalıştırma So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Babel (Gelişmiş) yapılandırma Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Eklentileri el ile belirtme Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Eklenti seçenekleri Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Ortama göre Babel'i özelleştirme Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Kendi önceden belirlenmiş ayarlarınızı yapmak Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babil ve diğer araçlar Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Statik analiz araçları Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Kod stili JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Dökümantasyon Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworkler All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Metin düzenleyicileri ve IDE'ler Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel destek Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel sohbet Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel sorunları Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Harika bir Babil hata raporu oluşturma Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/uk/plugin-handbook.md b/translations/uk/plugin-handbook.md index 1ae48634..3e2a2dfb 100644 --- a/translations/uk/plugin-handbook.md +++ b/translations/uk/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/uk/user-handbook.md b/translations/uk/user-handbook.md index c269bd9c..4be5d787 100644 --- a/translations/uk/user-handbook.md +++ b/translations/uk/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction + * [Introduction](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/vi/plugin-handbook.md b/translations/vi/plugin-handbook.md index 1ae48634..3e2a2dfb 100644 --- a/translations/vi/plugin-handbook.md +++ b/translations/vi/plugin-handbook.md @@ -8,60 +8,60 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Basics](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [Transform](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions](#definitions) - * [Builders](#builders) - * [Validators](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# Introduction + * [Introduction](#toc-introduction) + * [Basics](#toc-basics) + * [ASTs](#toc-asts) + * [Stages of Babel](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [Transform](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions](#toc-definitions) + * [Builders](#toc-builders) + * [Validators](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. @@ -73,11 +73,11 @@ You can use Babel to build many different types of tools that can help you be mo * * * -# Basics +# Basics Babel is a JavaScript compiler, specifically a source-to-source compiler, often called a "transpiler". This means that you give Babel some JavaScript code, Babel modifies the code, and generates the new code back out. -## ASTs +## ASTs Each of these steps involve creating or working with an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or AST. @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Stages of Babel The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ Each of the `type`s here have a set of properties describing the token: Like AST nodes they also have a `start`, `end`, and `loc`. -#### Syntactic Analysis +#### Syntactic Analysis Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### Transform +### Transform The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions +### Definitions Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders +### Builders You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### Validators +### Validators The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### Rename a binding and its references ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# Plugin Options If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# Building Nodes When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## Optimizing nested visitors When you are nesting visitors, it might make sense to write them nested in your code. @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## Being aware of nested structures Sometimes when thinking about a given transform, you might forget that the given structure can be nested. diff --git a/translations/vi/user-handbook.md b/translations/vi/user-handbook.md index c269bd9c..4be5d787 100644 --- a/translations/vi/user-handbook.md +++ b/translations/vi/user-handbook.md @@ -8,42 +8,42 @@ This handbook is available in other languages, see the [README](/README.md) for # Table of Contents - * [Introduction](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# Introduction + * [Introduction](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# Introduction Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -77,7 +77,7 @@ Many people do too, the ecosystem that has sprung up around Babel is massive and * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. diff --git a/translations/zh-Hans/plugin-handbook.md b/translations/zh-Hans/plugin-handbook.md index 637bde28..740fce54 100644 --- a/translations/zh-Hans/plugin-handbook.md +++ b/translations/zh-Hans/plugin-handbook.md @@ -8,60 +8,60 @@ # 目录 - * [介绍](#introduction) - * [基础](#basics) - * [抽象语法树（ASTs）](#asts) - * [Babel 的处理步骤](#stages-of-babel) - * [解析](#parse) - * [词法分析](#lexical-analysis) - * [语法分析](#syntactic-analysis) - * [转换](#transform) - * [生成](#generate) - * [遍历](#traversal) - * [Visitors（访问者）](#visitors) - * [Paths（路径）](#paths) - * [Paths in Visitors（存在于访问者中的路径）](#paths-in-visitors) - * [State（状态）](#state) - * [Scopes（作用域）](#scopes) - * [Bindings（绑定）](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [Definitions（定义）](#definitions) - * [Builders（构建器）](#builders) - * [Validators（验证器）](#validators) - * [Converters（变换器）](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [编写你的第一个 Babel 插件](#writing-your-first-babel-plugin) - * [转换操作](#transformation-operations) - * [访问](#visiting) - * [检查节点是否为某种特定类型](#check-if-a-node-is-a-certain-type) - * [检查标识符是否正在被引用着](#check-if-an-identifier-is-referenced) - * [处理](#manipulation) - * [替换节点](#replacing-a-node) - * [用多个节点替换一个节点](#replacing-a-node-with-multiple-nodes) - * [用字符串源码替换节点](#replacing-a-node-with-a-source-string) - * [插入同级节点](#inserting-a-sibling-node) - * [移除节点](#removing-a-node) - * [替换父节点](#replacing-a-parent) - * [移除父节点](#removing-a-parent) - * [Scope（作用域）](#scope) - * [检查本地变量是否有绑定](#checking-if-a-local-variable-is-bound) - * [生成唯一标识符（UID）](#generating-a-uid) - * [提升变量声明至父级作用域](#pushing-a-variable-declaration-to-a-parent-scope) - * [重命名绑定及其引用](#rename-a-binding-and-its-references) - * [插件选项](#plugin-options) - * [构建节点](#building-nodes) - * [最佳实践](#best-practices) - * [尽量避免遍历抽象语法树（AST）](#avoid-traversing-the-ast-as-much-as-possible) - * [及时合并访问者对象](#merge-visitors-whenever-possible) - * [可以手动查找就不要遍历](#do-not-traverse-when-manual-lookup-will-do) - * [优化嵌套的访问者对象](#optimizing-nested-visitors) - * [留意嵌套结构](#being-aware-of-nested-structures) - -# 介绍 + * [介绍](#toc-introduction) + * [基础](#toc-basics) + * [抽象语法树（ASTs）](#toc-asts) + * [Babel 的处理步骤](#toc-stages-of-babel) + * [解析](#toc-parse) + * [词法分析](#toc-lexical-analysis) + * [语法分析](#toc-syntactic-analysis) + * [转换](#toc-transform) + * [生成](#toc-generate) + * [遍历](#toc-traversal) + * [Visitors（访问者）](#toc-visitors) + * [Paths（路径）](#toc-paths) + * [Paths in Visitors（存在于访问者中的路径）](#toc-paths-in-visitors) + * [State（状态）](#toc-state) + * [Scopes（作用域）](#toc-scopes) + * [Bindings（绑定）](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [Definitions（定义）](#toc-definitions) + * [Builders（构建器）](#toc-builders) + * [Validators（验证器）](#toc-validators) + * [Converters（变换器）](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [编写你的第一个 Babel 插件](#toc-writing-your-first-babel-plugin) + * [转换操作](#toc-transformation-operations) + * [访问](#toc-visiting) + * [检查节点是否为某种特定类型](#toc-check-if-a-node-is-a-certain-type) + * [检查标识符是否正在被引用着](#toc-check-if-an-identifier-is-referenced) + * [处理](#toc-manipulation) + * [替换节点](#toc-replacing-a-node) + * [用多个节点替换一个节点](#toc-replacing-a-node-with-multiple-nodes) + * [用字符串源码替换节点](#toc-replacing-a-node-with-a-source-string) + * [插入同级节点](#toc-inserting-a-sibling-node) + * [移除节点](#toc-removing-a-node) + * [替换父节点](#toc-replacing-a-parent) + * [移除父节点](#toc-removing-a-parent) + * [Scope（作用域）](#toc-scope) + * [检查本地变量是否有绑定](#toc-checking-if-a-local-variable-is-bound) + * [生成唯一标识符（UID）](#toc-generating-a-uid) + * [提升变量声明至父级作用域](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [重命名绑定及其引用](#toc-rename-a-binding-and-its-references) + * [插件选项](#toc-plugin-options) + * [构建节点](#toc-building-nodes) + * [最佳实践](#toc-best-practices) + * [尽量避免遍历抽象语法树（AST）](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [及时合并访问者对象](#toc-merge-visitors-whenever-possible) + * [可以手动查找就不要遍历](#toc-do-not-traverse-when-manual-lookup-will-do) + * [优化嵌套的访问者对象](#toc-optimizing-nested-visitors) + * [留意嵌套结构](#toc-being-aware-of-nested-structures) + +# 介绍 Babel 是一个通用的多功能的 JavaScript 编译器。此外它还拥有众多模块可用于不同形式的静态分析。 @@ -73,11 +73,11 @@ Babel 是一个通用的多功能的 JavaScript 编译器。此外它还拥有 * * * -# 基础 +# 基础 Babel 是 JavaScript 编译器，更确切地说是源码到源码的编译器，通常也叫做“转换编译器（transpiler）”。 意思是说你为 Babel 提供一些 JavaScript 代码，Babel 更改这些代码，然后返回给你新生成的代码。 -## 抽象语法树（ASTs） +## 抽象语法树（ASTs） 这个处理过程中的每一步都涉及到创建或是操作[抽象语法树](https://en.wikipedia.org/wiki/Abstract_syntax_tree)，亦称 AST。 @@ -214,15 +214,15 @@ Babel 还为每个节点额外生成了一些属性，用于描述该节点在 每一个节点都会有 `start`，`end`，`loc` 这几个属性。 -## Babel 的处理步骤 +## Babel 的处理步骤 Babel 的三个主要处理步骤分别是： **解析（parse）**，**转换（transform）**，**生成（generate）**。. -### 解析 +### 解析 **解析**步骤接收代码并输出 AST。 这个步骤分为两个阶段：[**词法分析（Lexical Analysis） **](https://en.wikipedia.org/wiki/Lexical_analysis)和 [**语法分析（Syntactic Analysis）**](https://en.wikipedia.org/wiki/Parsing)。. -#### 词法分析 +#### 词法分析 词法分析阶段把字符串形式的代码转换为 **令牌（tokens）** 流。. @@ -264,21 +264,21 @@ n * n; 和 AST 节点一样它们也有 `start`，`end`，`loc` 属性。. -#### 语法分析 +#### 语法分析 语法分析阶段会把一个令牌流转换成 AST 的形式。 这个阶段会使用令牌中的信息把它们转换成一个 AST 的表述结构，这样更易于后续的操作。 -### 转换 +### 转换 [转换](https://en.wikipedia.org/wiki/Program_transformation)步骤接收 AST 并对其进行遍历，在此过程中对节点进行添加、更新及移除等操作。 这是 Babel 或是其他编译器中最复杂的过程 同时也是插件将要介入工作的部分，这将是本手册的主要内容， 因此让我们慢慢来。 -### 生成 +### 生成 [代码生成](https://en.wikipedia.org/wiki/Code_generation_(compiler))步骤把最终（经过一系列转换之后）的 AST转换成字符串形式的代码，同时创建[源码映射（source maps）](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/)。. 代码生成其实很简单：深度优先遍历整个 AST，然后构建可以表示转换后代码的字符串。 -## 遍历 +## 遍历 想要转换 AST 你需要进行递归的[树形遍历](https://en.wikipedia.org/wiki/Tree_traversal)。 @@ -330,7 +330,7 @@ n * n; Babel 的转换步骤全都是这样的遍历过程。 -### Visitors（访问者） +### Visitors（访问者） 当我们谈及“进入”一个节点，实际上是说我们在**访问**它们， 之所以使用这样的术语是因为有一个[**访问者模式（visitor）**](https://en.wikipedia.org/wiki/Visitor_pattern)的概念。. @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths（路径） +### Paths（路径） AST 通常会有许多节点，那么节点直接如何相互关联？ 我们可以用一个巨大的可变对象让你来操作以及完全访问（节点的关系），或者我们可以用**Paths（路径）**来简化这件事情。. @@ -485,7 +485,7 @@ AST 通常会有许多节点，那么节点直接如何相互关联？ 我们可 可以这么说，路径是对于节点在树中的位置以及其他各种信息的**响应式**表述。 当你调用一个方法更改了树的时候，这些信息也会更新。 Babel 帮你管理着这一切从而让你能更轻松的操作节点并且尽量保证无状态化。（译注：意即尽可能少的让你来维护状态） -#### Paths in Visitors（存在于访问者中的路径） +#### Paths in Visitors（存在于访问者中的路径） 当你有一个拥有 `Identifier()` 方法的访问者时，你实际上是在访问路径而不是节点。 如此一来你可以操作节点的响应式表述（译注：即路径）而不是节点本身。 @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State（状态） +### State（状态） 状态是 AST 转换的敌人。状态会不停的找你麻烦，你对状态的预估到最后几乎总是错的，因为你无法预先考虑到所有的语法。 @@ -572,7 +572,7 @@ const MyVisitor = { 当然，这只是一个刻意捏造的例子，不过它演示了如何从访问者中消除全局状态。 -### Scopes（作用域） +### Scopes（作用域） 接下来让我们引入[**作用域（scope）**](https://en.wikipedia.org/wiki/Scope_(computer_science))的概念。 JavaScript 拥有[词法作用域](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping)，代码块创建新的作用域并形成一个树状结构。 @@ -646,7 +646,7 @@ function scopeOne() { 这些做好之后，你将拥有许多用于作用域上的方法。我们稍后再讲这些。 -#### Bindings（绑定） +#### Bindings（绑定） 引用从属于特定的作用域；这种关系被称作：**绑定（binding）**。. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel 实际上是一系列的模块。本节我们将探索一些主要的模块，解释它们是做什么的以及如何使用它们。 > 注意：本节内容不是详细的 API 文档的替代品，正式的 API 文档将很快提供出来。 -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon 是 Babel 的解析器。最初是 Acorn 的一份 fork，它非常快，易于使用，并且针对非标准特性（以及那些未来的标准特性）设计了一个基于插件的架构。 @@ -753,7 +753,7 @@ babylon.parse(code, { 可以在 [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins) 查看所有插件的列表。. -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) Babel Tranverse（遍历）模块维护了整棵树的状态，并且负责替换、移除和添加节点。 @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types（类型）模块是一个用于 AST 节点的 Lodash 式工具库。 译注：Lodash 是一个 JavaScript 函数工具库，提供了基于函数式编程风格的众多工具函数）它包含了构造、验证以及变换 AST 节点的方法。 其设计周到的工具方法有助于编写清晰简单的 AST 逻辑。 @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### Definitions（定义） +### Definitions（定义） Babel Types模块拥有每一个单一类型节点的定义，包括有哪些属性分别属于哪里，哪些值是合法的，如何构建该节点，该节点应该如何去遍历，以及节点的别名等信息。 @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### Builders（构建器） +### Builders（构建器） 你会注意到上面的 `BinaryExpression` 定义有一个 `builder` 字段。. @@ -876,7 +876,7 @@ a * b 构建器还会验证自身创建的节点，并在错误使用的情形下抛出描述性的错误。这就引出了接下来的一种方法。 -### Validators（验证器） +### Validators（验证器） `BinaryExpression` 的定义还包含了节点的 `fields` 字段信息并且指示了如何验证它们。 @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters（变换器） +### Converters（变换器） > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator模块是 Babel 的代码生成器。它将 AST 输出为代码并包括源码映射（sourcemaps）。 @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template模块是一个很小但却非常有用的模块。它能让你编写带有占位符的字符串形式的代码，你可以用此来替代大量的手工构建的 AST。 @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# 编写你的第一个 Babel 插件 +# 编写你的第一个 Babel 插件 现在你已经熟悉了 Babel 的所有基础知识了，让我们把这些知识和插件的 API融合在一起来编写第一个 Babel 插件吧。 @@ -1113,11 +1113,11 @@ sebmck === dork; * * * -# 转换操作 +# 转换操作 -## 访问 +## 访问 -### 检查节点是否为某种特定类型 +### 检查节点是否为某种特定类型 要检查节点的类型是什么，比较好的方法是： @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### 检查标识符是否正在被引用着 +### 检查标识符是否正在被引用着 ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## 处理 +## 处理 -### 替换节点 +### 替换节点 ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### 用多个节点替换一个节点 +### 用多个节点替换一个节点 ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **注意：** 当用多个节点替换表达式时，这些节点必须是声明（statements）。 这是因为当节点替换发生时，Babel 极广泛地使用了启发式的算法，这意味着如果使用了非声明的代码会产生非常冗长的、疯狂的转换动作。 -### 用字符串源码替换节点 +### 用字符串源码替换节点 ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **注意：** 除非你要处理动态的源码字符串，否则不推荐使用这个 API，反之在访问者外部解析代码会更有效率。 -### 插入同级节点 +### 插入同级节点 ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **注意：** 这里同样应该使用声明或者一个声明数组。 因为使用了在[用多个节点替换一个节点](#replacing-a-node-with-multiple-nodes)一节提到的启发式算法。. -### 移除节点 +### 移除节点 ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### 替换父节点 +### 替换父节点 ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### 移除父节点 +### 移除父节点 ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope（作用域） +## Scope（作用域） -### 检查本地变量是否有绑定 +### 检查本地变量是否有绑定 ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### 生成唯一标识符（UID） +### 生成唯一标识符（UID） 这会生成一个不会和任何本地定义的变量冲突的标识符。 @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### 提升变量声明至父级作用域 +### 提升变量声明至父级作用域 有时你会需要提升一个 `VariableDeclaration` 以便可以给它赋值。 @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### 重命名绑定及其引用 +### 重命名绑定及其引用 ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# 插件选项 +# 插件选项 若你希望让你的用户自定义 Babel 插件的行为，你可以接收指定的选项： @@ -1424,7 +1424,7 @@ export default function({ types: t }) { * * * -# 构建节点 +# 构建节点 当编写转换动作时你会时常需要构建一些节点然后把它们插入到 AST 中。 正如之前提到的，你可以使用 [babel-types](#builder) 模块里的 [`Builders（构建器）`](#babel-types) 方法。 @@ -1535,17 +1535,17 @@ member.expression.property * * * -# 最佳实践 +# 最佳实践 > I'll be working on this section over the coming weeks. -## 尽量避免遍历抽象语法树（AST） +## 尽量避免遍历抽象语法树（AST） 遍历 AST 的代价很昂贵，并且很容易做出非必要的遍历，可能是数以千计甚或上万次的多余操作。 Babel 尽可能的对此做出了优化，方法是如果合并多个访问者能够在单次遍历做完所有事情的话那就合并它们。 -### 及时合并访问者对象 +### 及时合并访问者对象 当编写访问者时，若逻辑上必要的话，它会试图在多处调用 `path.traverse`。 @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### 可以手动查找就不要遍历 +### 可以手动查找就不要遍历 访问者也会尝试在查找一个特定节点类型时调用 `path.traverse`。 @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## 优化嵌套的访问者对象 +## 优化嵌套的访问者对象 当你嵌套访问者时，直接把它们嵌套式的写进代码里看起来很合理。 @@ -1675,7 +1675,7 @@ const MyVisitor = { }; ``` -## 留意嵌套结构 +## 留意嵌套结构 有时候在考虑一些转换时，你可能会忘记某些结构是可以嵌套的。 diff --git a/translations/zh-Hans/user-handbook.md b/translations/zh-Hans/user-handbook.md index e039fc58..f4aa8bff 100644 --- a/translations/zh-Hans/user-handbook.md +++ b/translations/zh-Hans/user-handbook.md @@ -8,42 +8,42 @@ # 目录 - * [介绍](#introduction) - * [安装 Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [在项目内运行 Babel CLI](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [配置 Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [执行 Babel 生成的代码](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [配置 Babel（进阶）](#configuring-babel-advanced) - * [手动指定插件](#manually-specifying-plugins) - * [插件选项](#plugin-options) - * [基于环境自定义 Babel](#customizing-babel-based-on-environment) - * [制作你自己的预设（preset）](#making-your-own-preset) - * [Babel 和其他工具](#babel-and-other-tools) - * [静态分析工具](#static-analysis-tools) - * [语法检查（Linting）](#linting) - * [代码风格](#code-style) - * [文档](#documentation) - * [框架](#frameworks) - * [React](#react) - * [文本编辑器和 IDEs（集成开发环境）](#text-editors-and-ides) - * [调试 Babel](#debugging-babel) - * [Babel 支持](#babel-support) - * [Babel 论坛](#babel-forum) - * [Babel 聊天](#babel-chat) - * [Babel 问题](#babel-issues) - * [创建漂亮的 Babel 错误报告](#creating-an-awesome-babel-bug-report) - -# 介绍 + * [介绍](#toc-introduction) + * [安装 Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [在项目内运行 Babel CLI](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [配置 Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [执行 Babel 生成的代码](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [配置 Babel（进阶）](#toc-configuring-babel-advanced) + * [手动指定插件](#toc-manually-specifying-plugins) + * [插件选项](#toc-plugin-options) + * [基于环境自定义 Babel](#toc-customizing-babel-based-on-environment) + * [制作你自己的预设（preset）](#toc-making-your-own-preset) + * [Babel 和其他工具](#toc-babel-and-other-tools) + * [静态分析工具](#toc-static-analysis-tools) + * [语法检查（Linting）](#toc-linting) + * [代码风格](#toc-code-style) + * [文档](#toc-documentation) + * [框架](#toc-frameworks) + * [React](#toc-react) + * [文本编辑器和 IDEs（集成开发环境）](#toc-text-editors-and-ides) + * [调试 Babel](#toc-debugging-babel) + * [Babel 支持](#toc-babel-support) + * [Babel 论坛](#toc-babel-forum) + * [Babel 聊天](#toc-babel-chat) + * [Babel 问题](#toc-babel-issues) + * [创建漂亮的 Babel 错误报告](#toc-creating-an-awesome-babel-bug-report) + +# 介绍 Babel 是一个通用的多用途 JavaScript 编译器。通过 Babel 你可以使用（并创建）下一代的 JavaScript，以及下一代的 JavaScript 工具。 @@ -77,7 +77,7 @@ const square = function square(n) { * * * -# 安装 Babel +# 安装 Babel 由于 JavaScript 社区没有统一的构建工具、框架、平台等等，因此 Babel 正式集成了对所有主流工具的支持。 从 Gulp 到 Browserify，从 Ember 到 Meteor，不管你的环境设置如何，Babel 都有正式的集成支持。 @@ -85,7 +85,7 @@ const square = function square(n) { > **注意：** 本手册将涉及到一些命令行工具如 `node` 和 `npm`。在继续阅读之前请确保你已经熟悉这些工具了。 -## `babel-cli` +## `babel-cli` Babel 的 CLI 是一种在命令行下使用 Babel 编译文件的简单方法。 @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### 在项目内运行 Babel CLI +### 在项目内运行 Babel CLI 尽管你*可以*把 Babel CLI 全局安装在你的机器上，但是按项目逐个安装在**本地**会更好。 @@ -171,7 +171,7 @@ npm run build 这将以与之前同样的方式运行 Babel，但这一次我们使用的是本地副本。 -## `babel-register` +## `babel-register` 下一个常用的运行 Babel 的方法是通过 `babel-register`。这种方法只需要引入文件就可以运行 Babel，或许能更好地融入你的项目设置。 @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` 如果你要用 `node` CLI 来运行代码，那么整合 Babel 最简单的方式就是使用 `babel-node` CLI，它是 `node` CLI 的替代品。 @@ -250,7 +250,7 @@ $ npm install --save-dev babel-cli > 提示：你可以使用 [`npm-run`](https://www.npmjs.com/package/npm-run)。. -## `babel-core` +## `babel-core` 如果你需要以编程的方式来使用 Babel，可以使用 `babel-core` 这个包。 @@ -297,7 +297,7 @@ babel.transformFromAst(ast, code, options); * * * -# 配置 Babel +# 配置 Babel 你或许已经注意到了，目前为止通过运行 Babel 自己我们并没能“翻译”代码，而仅仅是把代码从一处拷贝到了另一处。 @@ -307,7 +307,7 @@ babel.transformFromAst(ast, code, options); 你可以通过安装**插件（plugins）**或**预设（presets，也就是一组插件）**来指示 Babel 去做什么事情。 -## `.babelrc` +## `.babelrc` 在我们告诉 Babel 该做什么之前，我们需要创建一个配置文件。你需要做的就是在项目的根路径下创建 `.babelrc` 文件。然后输入以下内容作为开始： @@ -322,7 +322,7 @@ babel.transformFromAst(ast, code, options); > **注意：**尽管你也可以用其他方式给 Babel 传递选项，但 `.babelrc` 文件是约定也是最好的方式。 -## `babel-preset-es2015` +## `babel-preset-es2015` 我们先从让 Babel 把 ES2015（最新版本的 JavaScript 标准，也叫做 ES6）编译成 ES5（现今在大多数 JavaScript 环境下可用的版本）开始吧。 @@ -343,7 +343,7 @@ $ npm install --save-dev babel-preset-es2015 } ``` -## `babel-preset-react` +## `babel-preset-react` 设置 React 一样容易。只需要安装这个预设： @@ -363,7 +363,7 @@ $ npm install --save-dev babel-preset-react } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript 还有一些提案，正在积极通过 TC39（ECMAScript 标准背后的技术委员会）的流程成为标准的一部分。 @@ -401,11 +401,11 @@ $ npm install --save-dev babel-preset-stage-2 * * * -# 执行 Babel 生成的代码 +# 执行 Babel 生成的代码 即便你已经用 Babel 编译了你的代码，但这还不算完。 -## `babel-polyfill` +## `babel-polyfill` Babel 几乎可以编译所有时新的 JavaScript 语法，但对于 APIs 来说却并非如此。 @@ -448,7 +448,7 @@ $ npm install --save babel-polyfill import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` 为了实现 ECMAScript 规范的细节，Babel 会使用“助手”方法来保持生成代码的整洁。 @@ -504,11 +504,11 @@ let Foo = function () { * * * -# 配置 Babel（进阶） +# 配置 Babel（进阶） 大多数人使用 Babel 的内建预设就足够了，不过 Babel 提供了更多更细粒度的能力。 -## 手动指定插件 +## 手动指定插件 Babel 预设就是一些预先配置好的插件的集合，如果你想要做一些不一样的事情你会手动去设定插件，这和使用预设几乎完全相同。 @@ -534,7 +534,7 @@ $ npm install --save-dev babel-plugin-transform-es2015-classes 同时也别忘了看看[由社区构建的其他插件](https://www.npmjs.com/search?q=babel-plugin)。 如果你想学习如何编写自己的插件可以阅读 [Babel 插件手册](plugin-handbook.md)。. -## 插件选项 +## 插件选项 很多插件也有选项用于配置他们自身的行为。 例如，很多转换器都有“宽松”模式，通过放弃一些标准中的行为来生成更简化且性能更好的代码。 @@ -551,7 +551,7 @@ $ npm install --save-dev babel-plugin-transform-es2015-classes > 接下来几周内我会更新插件文档来详细介绍每一个选项。[关注我以获知更新](https://twitter.com/thejameskyle)。. -## 基于环境自定义 Babel +## 基于环境自定义 Babel 巴贝尔插件解决许多不同的问题。 其中大多数是开发工具，可以帮助你调试代码或是与工具集成。 也有大量的插件用于在生产环境中优化你的代码。 @@ -594,7 +594,7 @@ $ [COMMAND] > > **提示：**如果你想要让命令能够跨 unix 和 windows 平台运行的话，可以使用 [`cross-env`](https://www.npmjs.com/package/cross-env)。. -## 制作你自己的预设（preset） +## 制作你自己的预设（preset） 手动指定插件？插件选项？环境特定设置？所有这些配置都会在你的项目里产生大量的重复工作。 @@ -649,15 +649,15 @@ module.exports = { * * * -# Babel 和其他工具 +# Babel 和其他工具 一旦你掌握的窍门，安装 Babel 还是十分简明的，不过和其他工具搭配在一起就会变得困难多了。 不过我们一直在与其他项目密切合作以确保这种体验尽可能简单。 -## 静态分析工具 +## 静态分析工具 新标准为语言带来了许多新的语法，静态分析工具正在将此利用起来。 -### 语法检查（Linting） +### 语法检查（Linting） [ESLint](http://eslint.org) 是最流行的语法检查工具之一，因此我们维护了一个官方集成 [`babel-eslint`](https://github.com/babel/babel-eslint)。 @@ -703,11 +703,11 @@ $ npm run lint 详细信息请咨询 [`babel-eslint`](https://github.com/babel/babel-eslint) 或者 [`eslint`](http://eslint.org) 的文档。 -### 代码风格 +### 代码风格 JSCS 是一个极受欢迎的工具，在语法检查的基础上更进一步检查代码自身的风格。 Babel 和 JSCS 项目的核心维护者之一（[@hzoo](https://github.com/hzoo)）维护着 JSCS 的官方集成。 -更妙的是，JSCS 自己通过 `--exnext` 选项实现了这种集成，于是和 Babel 的集成就简化成了直接在命令行运行： +更妙的是，JSCS 自己通过 `--esnext` 选项实现了这种集成，于是和 Babel 的集成就简化成了直接在命令行运行： $ jscs . --esnext @@ -729,19 +729,19 @@ JSCS 是一个极受欢迎的工具，在语法检查的基础上更进一步检 > [WIP] --> -### 文档 +### 文档 使用 Babel，ES2015，还有 Flow 你可以对你的代码进行大量的推断。使用 [documentation.js](http://documentation.js.org) 可以非常简便地生成详细的 API 文档。 Documentation.js 使用 Babel 来支持所有最新的语法，包括用于在你的代码中声明类型所用的 Flow 注解在内， -## 框架 +## 框架 所有主流的 JavaScript 框架都正在努力调整他们的 APIs 向这门语言的未来看齐。有鉴于此，配套工具方面已经做出了大量的工作。 除了使用 Babel 以外，框架更有条件去扩展 Babel 来帮助他们提升用户体验。 -### React +### React React 已经大幅改变了他们的 API 以适应 ES2015 的类语法（[此处了解更新的 API](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)）。 再者，React 依赖 Babel 来编译它的 JSX 语法，并弃用了它自己的工具来支持 Babel。 你可以按照[上述说明](#babel-preset-react)安装 `babel-preset-react` 包来开始。. @@ -755,7 +755,7 @@ React 社区采用 Babel 并围绕它来运行，现在社区已经创建了[大 > [WIP] --> -## 文本编辑器和 IDEs（集成开发环境） +## 文本编辑器和 IDEs（集成开发环境） 通过 Babel 引入 ES2015，JSX，和流式语法固然是大有裨益，可如果你的文本编辑不支持那可就糟糕透了。 因此，别忘了为你的文本编辑器或是 IDE 安装 Babel 插件。 @@ -772,7 +772,7 @@ React 社区采用 Babel 并围绕它来运行，现在社区已经创建了[大 * * * -# Babel 支持 +# Babel 支持 Babel 的社区非常庞大并且增长速度很快，伴随着我们成长的同时我们希望保证人们总能获取他们需要的所有资源。 所以我们提供了数种途径来提供支持。 @@ -780,11 +780,11 @@ Babel 的社区非常庞大并且增长速度很快，伴随着我们成长的 同时我们也在寻求发展一个自我支持式的社区，为那些始终热诚奉献的人们。 如果别人问的问题你恰好知道答案，请不吝花费几分钟帮帮他们。 在此过程中也请尽力保持友善与相互理解。 -## Babel 论坛 +## Babel 论坛 [Discourse](http://www.discourse.org) 免费为我们提供了一个托管版本的论坛（我们爱死他们了！）。 如果你是个论坛控请不要错过 [discuss.babeljs.io](https://discuss.babeljs.io)。. -## Babel 聊天 +## Babel 聊天 无人不爱 [Slack](https://slack.com)。如果你正在寻求来自社区的即时支持，那就来 [slack.babeljs.io](https://slack.babeljs.io) 和我们聊天吧。. @@ -794,7 +794,7 @@ Babel 的社区非常庞大并且增长速度很快，伴随着我们成长的 > [WIP] --> -## Babel 问题 +## Babel 问题 Babel 使用了 [Phabricator](http://phabricator.org) 这个非常棒的问题跟踪应用，这是一个能让 Github 问题追踪变成昨日黄花的开源软件开发平台。 @@ -806,7 +806,7 @@ Babel 的 Phabricator 地址是：[phabricator.babeljs.io](https://phabricator.b * [登录](https://phabricator.babeljs.io/auth/start/)或[注册账号](https://phabricator.babeljs.io/auth/register/)（你可以使用 GitHub, Facebook, Twitter, Google 等账号直接登录) * [创建新的错误报告](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R)或者[请求新的功能特性](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### 创建漂亮的 Babel 错误报告 +### 创建漂亮的 Babel 错误报告 Babel 的问题有时候很难远程调试，所以我们希望能获取尽可能详细的信息来帮助我们解决问题。 花点时间去撰写一份好的错误报告会让你的问题更快得到解决。 diff --git a/translations/zh-Hant/README.md b/translations/zh-Hant/README.md index 5596e5fd..42bf7219 100644 --- a/translations/zh-Hant/README.md +++ b/translations/zh-Hant/README.md @@ -1,10 +1,10 @@ -# Babel使用手冊 +# Babel 使用手冊 這本手冊分成兩個部分： - * [使用者手冊](user-handbook.md) - 如何安裝與配置Babel - * [外掛手冊](plugin-handbook.md) - 如何建造Babel使用的外掛 + * [使用者手冊](user-handbook.md) - 如何安裝與配置 Babel + * [外掛手冊](plugin-handbook.md) - 如何建造 Babel 使用的外掛 -> 更多的最新資訊，請上[@thejameskyle](https://twitter.com/thejameskyle)的Twitter查詢。 +> 更多的最新資訊，請上[@thejameskyle](https://twitter.com/thejameskyle)的 Twitter 查詢。 -如果你正閱讀這本分英語系的手冊，你會發現仍有尚未翻譯完成的部分。 如果你想要協助翻譯這份文件必須要透過 Crowdin來翻譯。 請閱讀 [協助準則](/CONTRIBUTING.md)以獲得更多資訊。 你會發現大量程式設計的用詞或英語單詞， 如果被翻譯之後將會造成閱讀上缺發連貫性與流暢性。 另外，某些情況下會發現 `()`內字面上的翻譯會沿用英文的術語。 舉例子來說： Abstract Syntax Trees (ASTs). \ No newline at end of file +如果你正閱讀這本分英語系的手冊，你會發現仍有尚未翻譯完成的部分。 如果你想要協助翻譯這份文件必須要透過 Crowdin 來翻譯。 請閱讀 [協助準則](/CONTRIBUTING.md) 以獲得更多資訊。 你會發現大量程式設計的用詞或英語單詞， 如果被翻譯之後將會造成閱讀上缺發連貫性與流暢性。 另外，某些情況下會發現 `()`內字面上的翻譯會沿用英文的術語。 舉例子來說： Abstract Syntax Trees (ASTs). \ No newline at end of file diff --git a/translations/zh-Hant/plugin-handbook.md b/translations/zh-Hant/plugin-handbook.md index ce54ba2a..25e95443 100644 --- a/translations/zh-Hant/plugin-handbook.md +++ b/translations/zh-Hant/plugin-handbook.md @@ -8,80 +8,80 @@ # 目錄 - * [簡介](#introduction) - * [基本功能](#basics) - * [ASTs](#asts) - * [Stages of Babel](#stages-of-babel) - * [Parse](#parse) - * [Lexical Analysis](#lexical-analysis) - * [Syntactic Analysis](#syntactic-analysis) - * [轉換](#transform) - * [Generate](#generate) - * [Traversal](#traversal) - * [Visitors](#visitors) - * [Paths](#paths) - * [Paths in Visitors](#paths-in-visitors) - * [State](#state) - * [Scopes](#scopes) - * [Bindings](#bindings) - * [API](#api) - * [babylon](#babylon) - * [babel-traverse](#babel-traverse) - * [babel-types](#babel-types) - * [定義](#definitions) - * [建置](#builders) - * [驗證](#validators) - * [Converters](#converters) - * [babel-generator](#babel-generator) - * [babel-template](#babel-template) - * [Writing your first Babel Plugin](#writing-your-first-babel-plugin) - * [Transformation Operations](#transformation-operations) - * [Visiting](#visiting) - * [Check if a node is a certain type](#check-if-a-node-is-a-certain-type) - * [Check if an identifier is referenced](#check-if-an-identifier-is-referenced) - * [Manipulation](#manipulation) - * [Replacing a node](#replacing-a-node) - * [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes) - * [Replacing a node with a source string](#replacing-a-node-with-a-source-string) - * [Inserting a sibling node](#inserting-a-sibling-node) - * [Removing a node](#removing-a-node) - * [Replacing a parent](#replacing-a-parent) - * [Removing a parent](#removing-a-parent) - * [Scope](#scope) - * [Checking if a local variable is bound](#checking-if-a-local-variable-is-bound) - * [Generating a UID](#generating-a-uid) - * [Pushing a variable declaration to a parent scope](#pushing-a-variable-declaration-to-a-parent-scope) - * [Rename a binding and its references](#rename-a-binding-and-its-references) - * [Plugin Options](#plugin-options) - * [Building Nodes](#building-nodes) - * [Best Practices](#best-practices) - * [Avoid traversing the AST as much as possible](#avoid-traversing-the-ast-as-much-as-possible) - * [Merge visitors whenever possible](#merge-visitors-whenever-possible) - * [Do not traverse when manual lookup will do](#do-not-traverse-when-manual-lookup-will-do) - * [Optimizing nested visitors](#optimizing-nested-visitors) - * [Being aware of nested structures](#being-aware-of-nested-structures) - -# 簡介 - -Babel is a generic multi-purpose compiler for JavaScript. More than that it is a collection of modules that can be used for many different forms of static analysis. - -> Static analysis is the process of analyzing code without executing it. (Analysis of code while executing it is known as dynamic analysis). The purpose of static analysis varies greatly. It can be used for linting, compiling, code highlighting, code transformation, optimization, minification, and much more. - -You can use Babel to build many different types of tools that can help you be more productive and write better programs. - -> ***更多的最新資訊，請上[@thejameskyle](https://twitter.com/thejameskyle)的Twitter查詢。*** + * [簡介](#toc-introduction) + * [基本功能](#toc-basics) + * [ASTs (抽象語法樹)](#toc-asts) + * [Babel 的階段](#toc-stages-of-babel) + * [Parse](#toc-parse) + * [Lexical Analysis](#toc-lexical-analysis) + * [Syntactic Analysis](#toc-syntactic-analysis) + * [轉換](#toc-transform) + * [Generate](#toc-generate) + * [Traversal](#toc-traversal) + * [Visitors](#toc-visitors) + * [Paths](#toc-paths) + * [Paths in Visitors](#toc-paths-in-visitors) + * [State](#toc-state) + * [Scopes](#toc-scopes) + * [Bindings](#toc-bindings) + * [API](#toc-api) + * [babylon](#toc-babylon) + * [babel-traverse](#toc-babel-traverse) + * [babel-types](#toc-babel-types) + * [定義](#toc-definitions) + * [建置](#toc-builders) + * [驗證](#toc-validators) + * [Converters](#toc-converters) + * [babel-generator](#toc-babel-generator) + * [babel-template](#toc-babel-template) + * [Writing your first Babel Plugin](#toc-writing-your-first-babel-plugin) + * [Transformation Operations](#toc-transformation-operations) + * [Visiting](#toc-visiting) + * [Check if a node is a certain type](#toc-check-if-a-node-is-a-certain-type) + * [Check if an identifier is referenced](#toc-check-if-an-identifier-is-referenced) + * [Manipulation](#toc-manipulation) + * [Replacing a node](#toc-replacing-a-node) + * [Replacing a node with multiple nodes](#toc-replacing-a-node-with-multiple-nodes) + * [Replacing a node with a source string](#toc-replacing-a-node-with-a-source-string) + * [Inserting a sibling node](#toc-inserting-a-sibling-node) + * [Removing a node](#toc-removing-a-node) + * [Replacing a parent](#toc-replacing-a-parent) + * [Removing a parent](#toc-removing-a-parent) + * [Scope](#toc-scope) + * [Checking if a local variable is bound](#toc-checking-if-a-local-variable-is-bound) + * [Generating a UID](#toc-generating-a-uid) + * [Pushing a variable declaration to a parent scope](#toc-pushing-a-variable-declaration-to-a-parent-scope) + * [Rename a binding and its references](#toc-rename-a-binding-and-its-references) + * [Plugin Options](#toc-plugin-options) + * [Building Nodes](#toc-building-nodes) + * [Best Practices](#toc-best-practices) + * [Avoid traversing the AST as much as possible](#toc-avoid-traversing-the-ast-as-much-as-possible) + * [Merge visitors whenever possible](#toc-merge-visitors-whenever-possible) + * [Do not traverse when manual lookup will do](#toc-do-not-traverse-when-manual-lookup-will-do) + * [Optimizing nested visitors](#toc-optimizing-nested-visitors) + * [Being aware of nested structures](#toc-being-aware-of-nested-structures) + +# 簡介 + +Babel 是一個廣泛、多目的的 Javascript 編譯器。不止這樣，它還是多個模組的集合，可以讓我們做各種不同的靜態解析。 + +> 靜態解析是指我們可以直接分析程式碼而不用去執行它們。 （若是需要執行才能解析，就是一般我們所熟知的動態解析。） 靜態解析的目的非常多樣， 可以用於：linting, compiling, code highlighting, code transformation, optimization, minification 或其他更多的地方 + +使用 Babel 可以建構各種不同的工具，幫助你更有效的製作產品或是寫出好的程式。 + +> ***更多的最新資訊，請上 [@thejameskyle](https://twitter.com/thejameskyle) 的 Twitter 查詢。*** * * * -# 基本功能 +# 基本功能 -Babel是一個JavaScript compiler, 因為是source-to-source而非source-to-binary的compiler，所以通常又稱為"transpiler"。 這表示當你餵給Babel一些JavaScript code，Babel 會將之修改之後，回給你一份修改後的新code。 +Babel 是一個 JavaScript compiler，因為是 source-to-source 而非 source-to-binary 的 compiler，所以通常又稱為 "transpiler"。 這表示當你餵給 Babel 一些 JavaScript code，Babel 會將之修改之後，回給你一份修改後的新 code。 -## ASTs +## ASTs (抽象語法樹) -每一個步驟包含[Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree)或AST的建造或是使用 +每一個步驟包含 [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) 或 AST 的建造或是使用 -> Babel 在 [ESTree](https://github.com/estree/estree)上使用AST來修改，其主要規範可以在[這裡](https://github.com/babel/babel/blob/master/doc/ast/spec.md)找到。. +> Babel 在 [ESTree](https://github.com/estree/estree)上使用 AST 來修改，其主要規範可以在[這裡](https://github.com/babel/babel/blob/master/doc/ast/spec.md)找到。. ```js function square(n) { @@ -89,7 +89,7 @@ function square(n) { } ``` -> 在 [AST Explorer](http://astexplorer.net/)中可以對AST nodes有更深入的了解， [點我](http://astexplorer.net/#/Z1exs6BWMq)可以連到上述範例代碼的頁面。 +> 在 [AST Explorer](http://astexplorer.net/)中可以對 AST nodes 有更深入的了解， [點我](http://astexplorer.net/#/Z1exs6BWMq)可以連到上述範例代碼的頁面。 像這樣的程式可以代表一份清單： @@ -214,15 +214,15 @@ There are additional properties on every Node that Babel generates which describ These properties `start`, `end`, `loc`, appear in every single Node. -## Stages of Babel +## Babel 的階段 The three primary stages of Babel are **parse**, **transform**, **generate**. -### Parse +### Parse The **parse** stage, takes code and outputs an AST. There are two phases of parsing in Babel: [**Lexical Analysis**](https://en.wikipedia.org/wiki/Lexical_analysis) and [**Syntactic Analysis**](https://en.wikipedia.org/wiki/Parsing). -#### Lexical Analysis +#### Lexical Analysis Lexical Analysis will take a string of code and turn it into a stream of **tokens**. @@ -264,21 +264,21 @@ n * n; Like AST nodes they also have a `start`, `end`, and `loc`. -#### 語意分析 +#### 語意分析 Syntactic Analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of the code in a way that makes it easier to work with. -### 轉換 +### 轉換 The [transform](https://en.wikipedia.org/wiki/Program_transformation) stage takes an AST and traverses through it, adding, updating, and removing nodes as it goes along. This is by far the most complex part of Babel or any compiler. This is where plugins operate and so it will be the subject of most of this handbook. So we won't dive too deep right now. -### Generate +### Generate The [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)) stage takes the final AST and turns in back into a string of code, also creating [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). Code generation is pretty simple: you traverse through the AST depth-first, building a string that represents the transformed code. -## Traversal +## Traversal When you want to transform an AST you have to [traverse the tree](https://en.wikipedia.org/wiki/Tree_traversal) recursively. @@ -330,7 +330,7 @@ The `BinaryExpression` has an `operator`, a `left`, and a `right`. The operator This traversal process happens throughout the Babel transform stage. -### Visitors +### Visitors When we talk about "going" to a node, we actually mean we are **visiting** them. The reason we use that term is because there is this concept of a [**visitor**](https://en.wikipedia.org/wiki/Visitor_pattern). @@ -418,7 +418,7 @@ const MyVisitor = { }; ``` -### Paths +### Paths An AST generally has many Nodes, but how do Nodes relate to one another? We could have one giant mutable object that you manipulate and have full access to, or we can simplify this with **Paths**. @@ -485,7 +485,7 @@ As well as tons and tons of methods related to adding, updating, moving, and rem In a sense, paths are a **reactive** representation of a node's position in the tree and all sorts of information about the node. Whenever you call a method that modifies the tree, this information is updated. Babel manages all of this for you to make working with nodes easy and as stateless as possible. -#### Paths in Visitors +#### Paths in Visitors When you have a visitor that has a `Identifier()` method, you're actually visiting the path instead of the node. This way you are mostly working with the reactive representation of a node instead of the node itself. @@ -507,7 +507,7 @@ Visiting: b Visiting: c ``` -### State +### State State is the enemy of AST transformation. State will bite you over and over again and your assumptions about state will almost always be proven wrong by some syntax that you didn't consider. @@ -572,7 +572,7 @@ const MyVisitor = { Of course, this is a contrived example but it demonstrates how to eliminate global state from your visitors. -### Scopes +### Scopes Next let's introduce the concept of a [**scope**](https://en.wikipedia.org/wiki/Scope_(computer_science)). JavaScript has [lexical scoping](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping_vs._dynamic_scoping), which is a tree structure where blocks create new scope. @@ -646,7 +646,7 @@ When you create a new scope you do so by giving it a path and a parent scope. Th Once that's done, there's all sorts of methods you can use on scopes. We'll get into those later though. -#### Bindings +#### Bindings References all belong to a particular scope; this relationship is known as a **binding**. @@ -699,13 +699,13 @@ function scopeOne() { * * * -# API +# API Babel is actually a collection of modules. In this section we'll walk through the major ones, explaining what they do and how to use them. > Note: This is not a replacement for detailed API documentation which will be available elsewhere shortly. -## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) +## [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon) Babylon is Babel's parser. Started as a fork of Acorn, it's fast, simple to use, has plugin-based architecture for non-standard features (as well as future standards). @@ -753,7 +753,7 @@ Since Babylon is built with a plugin-based architecture, there is also a `plugin To see a full list of plugins, see the [Babylon README](https://github.com/babel/babel/blob/master/packages/babylon/README.md#plugins). -## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) +## [`babel-traverse`](https://github.com/babel/babel/tree/master/packages/babel-traverse) The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes. @@ -787,7 +787,7 @@ traverse(ast, { }); ``` -## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) +## [`babel-types`](https://github.com/babel/babel/tree/master/packages/babel-types) Babel Types is a Lodash-esque utility library for AST nodes. It contains methods for building, validating, and converting AST nodes. It's useful for cleaning up AST logic with well thought out utility methods. @@ -812,7 +812,7 @@ traverse(ast, { }); ``` -### 定義 +### 定義 Babel Types has definitions for every single type of node, with information on what properties belong where, what values are valid, how to build that node, how the node should be traversed, and aliases of the Node. @@ -837,7 +837,7 @@ defineType("BinaryExpression", { }); ``` -### 建置 +### 建置 You'll notice the above definition for `BinaryExpression` has a field for a `builder`. @@ -876,7 +876,7 @@ a * b Builders will also validate the nodes they are creating and throw descriptive errors if used improperly. Which leads into the next type of method. -### 驗證 +### 驗證 The definition for `BinaryExpression` also includes information on the `fields` of a node and how to validate them. @@ -914,11 +914,11 @@ t.assertBinaryExpression(maybeBinaryExpressionNode, { operator: "*" }); // Error: Expected type "BinaryExpression" with option { "operator": "*" } ``` -### Converters +### Converters > [WIP] -## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) +## [`babel-generator`](https://github.com/babel/babel/tree/master/packages/babel-generator) Babel Generator is the code generator for Babel. It takes an AST and turns it into code with sourcemaps. @@ -959,7 +959,7 @@ generate(ast, { }, code); ``` -## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) +## [`babel-template`](https://github.com/babel/babel/tree/master/packages/babel-template) Babel Template is another tiny but incredibly useful module. It allows you to write strings of code with placeholders that you can use instead of manually building up a massive AST. @@ -988,7 +988,7 @@ console.log(generate(ast).code); var myModule = require("my-module"); ``` -# Writing your first Babel Plugin +# Writing your first Babel Plugin Now that you're familiar with all the basics of Babel, let's tie it together with the plugin API. @@ -1113,11 +1113,11 @@ Awesome! Our very first Babel plugin. * * * -# Transformation Operations +# Transformation Operations -## Visiting +## Visiting -### Check if a node is a certain type +### Check if a node is a certain type If you want to check what the type of a node is, the preferred way to do so is: @@ -1153,7 +1153,7 @@ BinaryExpression(path) { } ``` -### Check if an identifier is referenced +### Check if an identifier is referenced ```js Identifier(path) { @@ -1173,9 +1173,9 @@ Identifier(path) { } ``` -## Manipulation +## Manipulation -### Replacing a node +### Replacing a node ```js BinaryExpression(path) { @@ -1192,7 +1192,7 @@ BinaryExpression(path) { } ``` -### Replacing a node with multiple nodes +### Replacing a node with multiple nodes ```js ReturnStatement(path) { @@ -1215,7 +1215,7 @@ ReturnStatement(path) { > **Note:** When replacing an expression with multiple nodes, they must be statements. This is because Babel uses heuristics extensively when replacing nodes which means that you can do some pretty crazy transformations that would be extremely verbose otherwise. -### Replacing a node with a source string +### Replacing a node with a source string ```js FunctionDeclaration(path) { @@ -1235,7 +1235,7 @@ FunctionDeclaration(path) { > **Note:** It's not recommended to use this API unless you're dealing with dynamic source strings, otherwise it's more efficient to parse the code outside of the visitor. -### Inserting a sibling node +### Inserting a sibling node ```js FunctionDeclaration(path) { @@ -1254,7 +1254,7 @@ FunctionDeclaration(path) { > **Note:** This should always be a statement or an array of statements. This uses the same heuristics mentioned in [Replacing a node with multiple nodes](#replacing-a-node-with-multiple-nodes). -### Removing a node +### Removing a node ```js FunctionDeclaration(path) { @@ -1268,7 +1268,7 @@ FunctionDeclaration(path) { - } ``` -### Replacing a parent +### Replacing a parent ```js BinaryExpression(path) { @@ -1285,7 +1285,7 @@ BinaryExpression(path) { } ``` -### Removing a parent +### Removing a parent ```js BinaryExpression(path) { @@ -1299,9 +1299,9 @@ BinaryExpression(path) { } ``` -## Scope +## Scope -### Checking if a local variable is bound +### Checking if a local variable is bound ```js FunctionDeclaration(path) { @@ -1323,7 +1323,7 @@ FunctionDeclaration(path) { } ``` -### Generating a UID +### Generating a UID This will generate an identifier that doesn't collide with any locally defined variables. @@ -1336,7 +1336,7 @@ FunctionDeclaration(path) { } ``` -### Pushing a variable declaration to a parent scope +### Pushing a variable declaration to a parent scope Sometimes you may want to push a `VariableDeclaration` so you can assign to it. @@ -1356,7 +1356,7 @@ FunctionDeclaration(path) { + }; ``` -### Rename a binding and its references +### 重新為綁定命名與參照 ```js FunctionDeclaration(path) { @@ -1372,7 +1372,7 @@ FunctionDeclaration(path) { } ``` -Alternatively, you can rename a binding to a generated unique identifier: +或者，你可以重新為綁定命名並給予一個獨特的身份。 ```js FunctionDeclaration(path) { @@ -1390,7 +1390,7 @@ FunctionDeclaration(path) { * * * -# Plugin Options +# 外掛選擇 If you would like to let your users customize the behavior of your Babel plugin you can accept plugin specific options which users can specify like this: @@ -1424,7 +1424,7 @@ These options are plugin-specific and you cannot access options from other plugi * * * -# Building Nodes +# 節點構成 When writing transformations you'll often want to build up some nodes to insert into the AST. As mentioned previously, you can do this using the [builder](#builder) methods in the [`babel-types`](#babel-types) package. @@ -1535,17 +1535,17 @@ You can find all of the actual [definitions here](https://github.com/babel/babel * * * -# Best Practices +# Best Practices > I'll be working on this section over the coming weeks. -## Avoid traversing the AST as much as possible +## Avoid traversing the AST as much as possible Traversing the AST is expensive, and it's easy to accidentally traverse the AST more than necessary. This could be thousands if not tens of thousands of extra operations. Babel optimizes this as much as possible, merging visitors together if it can in order to do everything in a single traversal. -### Merge visitors whenever possible +### Merge visitors whenever possible When writing visitors, it may be tempting to call `path.traverse` in multiple places where they are logically necessary. @@ -1576,7 +1576,7 @@ path.traverse({ }); ``` -### Do not traverse when manual lookup will do +### Do not traverse when manual lookup will do It may also be tempting to call `path.traverse` when looking for a particular node type. @@ -1606,7 +1606,7 @@ const MyVisitor = { }; ``` -## Optimizing nested visitors +## 優化巢狀的尋訪 When you are nesting visitors, it might make sense to write them nested in your code. @@ -1638,7 +1638,7 @@ const MyVisitor = { }; ``` -If you need some state within the nested visitor, like so: +如果你需要一些狀態給予 nested visitor，就像： ```js const MyVisitor = { @@ -1656,7 +1656,7 @@ const MyVisitor = { }; ``` -You can pass it in as state to the `traverse()` method and have access to it on `this` in the visitor. +你可以將它作為狀態傳遞給 `traverse()` 方法並且同意`this`尋訪 ```js const visitorOne = { @@ -1675,11 +1675,11 @@ const MyVisitor = { }; ``` -## Being aware of nested structures +## 根據巢狀結構 -Sometimes when thinking about a given transform, you might forget that the given structure can be nested. +有時候直覺思考著如何轉換，也許可能會因而忽略掉這是可以建構成巢狀的結構。 -For example, imagine we want to lookup the `constructor` `ClassMethod` from the `Foo` `ClassDeclaration`. +舉個例子來說，想像我們正從`Foo` `ClassDeclaration `尋找著`節構``函式`。. ```js class Foo { @@ -1721,4 +1721,4 @@ class Foo { } ``` -> ***更多的最新資訊，請上[@thejameskyle](https://twitter.com/thejameskyle)的Twitter查詢。*** \ No newline at end of file +> ***更多的最新資訊，請上[@thejameskyle](https://twitter.com/thejameskyle)的 Twitter 查詢。*** \ No newline at end of file diff --git a/translations/zh-Hant/user-handbook.md b/translations/zh-Hant/user-handbook.md index b54e80aa..6c4d801b 100644 --- a/translations/zh-Hant/user-handbook.md +++ b/translations/zh-Hant/user-handbook.md @@ -8,42 +8,42 @@ This document covers everything you ever wanted to know about using [Babel](http # 目錄 - * [簡介](#introduction) - * [Setting up Babel](#setting-up-babel) - * [`babel-cli`](#babel-cli) - * [Running Babel CLI from within a project](#running-babel-cli-from-within-a-project) - * [`babel-register`](#babel-register) - * [`babel-node`](#babel-node) - * [`babel-core`](#babel-core) - * [Configuring Babel](#configuring-babel) - * [`.babelrc`](#babelrc) - * [`babel-preset-es2015`](#babel-preset-es2015) - * [`babel-preset-react`](#babel-preset-react) - * [`babel-preset-stage-x`](#babel-preset-stage-x) - * [Executing Babel-generated code](#executing-babel-generated-code) - * [`babel-polyfill`](#babel-polyfill) - * [`babel-runtime`](#babel-runtime) - * [Configuring Babel (Advanced)](#configuring-babel-advanced) - * [Manually specifying plugins](#manually-specifying-plugins) - * [Plugin options](#plugin-options) - * [Customizing Babel based on environment](#customizing-babel-based-on-environment) - * [Making your own preset](#making-your-own-preset) - * [Babel and other tools](#babel-and-other-tools) - * [Static analysis tools](#static-analysis-tools) - * [Linting](#linting) - * [Code Style](#code-style) - * [Documentation](#documentation) - * [Frameworks](#frameworks) - * [React](#react) - * [Text Editors and IDEs](#text-editors-and-ides) - * [Debugging Babel](#debugging-babel) - * [Babel Support](#babel-support) - * [Babel Forum](#babel-forum) - * [Babel Chat](#babel-chat) - * [Babel Issues](#babel-issues) - * [Creating an awesome Babel bug report](#creating-an-awesome-babel-bug-report) - -# 簡介 + * [簡介](#toc-introduction) + * [Setting up Babel](#toc-setting-up-babel) + * [`babel-cli`](#toc-babel-cli) + * [Running Babel CLI from within a project](#toc-running-babel-cli-from-within-a-project) + * [`babel-register`](#toc-babel-register) + * [`babel-node`](#toc-babel-node) + * [`babel-core`](#toc-babel-core) + * [Configuring Babel](#toc-configuring-babel) + * [`.babelrc`](#toc-babelrc) + * [`babel-preset-es2015`](#toc-babel-preset-es2015) + * [`babel-preset-react`](#toc-babel-preset-react) + * [`babel-preset-stage-x`](#toc-babel-preset-stage-x) + * [Executing Babel-generated code](#toc-executing-babel-generated-code) + * [`babel-polyfill`](#toc-babel-polyfill) + * [`babel-runtime`](#toc-babel-runtime) + * [Configuring Babel (Advanced)](#toc-configuring-babel-advanced) + * [Manually specifying plugins](#toc-manually-specifying-plugins) + * [Plugin options](#toc-plugin-options) + * [Customizing Babel based on environment](#toc-customizing-babel-based-on-environment) + * [Making your own preset](#toc-making-your-own-preset) + * [Babel and other tools](#toc-babel-and-other-tools) + * [Static analysis tools](#toc-static-analysis-tools) + * [Linting](#toc-linting) + * [Code Style](#toc-code-style) + * [Documentation](#toc-documentation) + * [Frameworks](#toc-frameworks) + * [React](#toc-react) + * [Text Editors and IDEs](#toc-text-editors-and-ides) + * [Debugging Babel](#toc-debugging-babel) + * [Babel Support](#toc-babel-support) + * [Babel Forum](#toc-babel-forum) + * [Babel Chat](#toc-babel-chat) + * [Babel Issues](#toc-babel-issues) + * [Creating an awesome Babel bug report](#toc-creating-an-awesome-babel-bug-report) + +# 簡介 Babel is a generic multi-purpose compiler for JavaScript. Using Babel you can use (and create) the next generation of JavaScript, as well as the next generation of JavaScript tooling. @@ -73,11 +73,11 @@ Further than that, everything in Babel is simply a plugin and anyone can go out Many people do too, the ecosystem that has sprung up around Babel is massive and very diverse. Throughout this handbook I'll be covering both how built-in Babel tools work as well as some useful things from around the community. -> ***更多的最新資訊，請上[@thejameskyle](https://twitter.com/thejameskyle)的Twitter查詢。*** +> ***更多的最新資訊，請上[@thejameskyle](https://twitter.com/thejameskyle)的 Twitter 查詢。*** * * * -# Setting up Babel +# Setting up Babel Since the JavaScript community has no single build tool, framework, platform, etc., Babel has official integrations for all of the major tooling. Everything from Gulp to Browserify, from Ember to Meteor, no matter what your setup looks like there is probably an official integration. @@ -85,7 +85,7 @@ For the purposes of this handbook, we're just going to cover the built-in ways o > **Note:** This guide is going to refer to command line tools like `node` and `npm`. Before continuing any further you should be comfortable with these tools. -## `babel-cli` +## `babel-cli` Babel's CLI is a simple way to compile files with Babel from the command line. @@ -117,7 +117,7 @@ $ babel src --out-dir lib $ babel src -d lib ``` -### Running Babel CLI from within a project +### Running Babel CLI from within a project While you *can* install Babel CLI globally on your machine, it's much better to install it **locally** project by project. @@ -171,7 +171,7 @@ npm run build This will run Babel the same way as before, only now we are using a local copy. -## `babel-register` +## `babel-register` The next most common method of running Babel is through `babel-register`. This option will allow you to run Babel just by requiring files, which may integrate with your setup better. @@ -214,7 +214,7 @@ require("babel-register"); console.log("Hello world!"); ``` -## `babel-node` +## `babel-node` If you are just running some code via the `node` CLI the easiest way to integrate Babel might be to use the `babel-node` CLI which largely is just a drop in replacement for the `node` CLI. @@ -250,7 +250,7 @@ Otherwise you'll need to write out the path to `babel-node` itself. > Tip: You can also use [`npm-run`](https://www.npmjs.com/package/npm-run). -## `babel-core` +## `babel-core` If you need to use Babel programmatically for some reason, you can use the `babel-core` package itself. @@ -297,7 +297,7 @@ For all of the above methods, `options` refers to http://babeljs.io/docs/usage/o * * * -# Configuring Babel +# Configuring Babel You may have noticed by now that running Babel on its own doesn't seem to do anything other than copy JavaScript files from one location to another. @@ -307,7 +307,7 @@ This is because we haven't told Babel to do anything yet. You can give Babel instructions on what to do by installing **plugins** or **presets** (groups of plugins). -## `.babelrc` +## `.babelrc` Before we start telling Babel what to do. We need to create a configuration file. All you need to do is create a `.babelrc` file at the root of your project. Start off with it like this: @@ -322,7 +322,7 @@ This file is how you configure Babel to do what you want. > **Note:** While you can also pass options to Babel in other ways the `.babelrc` file is convention and is the best way. -## `babel-preset-es2015` +## `babel-preset-es2015` Let's start by telling Babel to compile ES2015 (the newest version of the JavaScript standard, also known as ES6) to ES5 (the version available in most JavaScript environments today). @@ -343,7 +343,7 @@ Next we'll modify our `.babelrc` to include that preset. } ``` -## `babel-preset-react` +## `babel-preset-react` Setting up React is just as easy. Just install the preset: @@ -363,7 +363,7 @@ Then add the preset to your `.babelrc` file: } ``` -## `babel-preset-stage-x` +## `babel-preset-stage-x` JavaScript also has some proposals that are making their way into the standard through the TC39's (the technical committee behind the ECMAScript standard) process. @@ -401,11 +401,11 @@ Then you can add it to your `.babelrc` config. * * * -# Executing Babel-generated code +# Executing Babel-generated code So you've compiled your code with Babel, but this is not the end of the story. -## `babel-polyfill` +## `babel-polyfill` Almost all futuristic JavaScript syntax can be compiled with Babel, but the same is not true for APIs. @@ -448,7 +448,7 @@ Then simply include the polyfill at the top of any file that requires it: import "babel-polyfill"; ``` -## `babel-runtime` +## `babel-runtime` In order to implement details of ECMAScript specs, Babel will use "helper" methods in order to keep the generated code clean. @@ -504,11 +504,11 @@ Rather than putting the `_classCallCheck` and `_createClass` helpers in every si * * * -# Configuring Babel (Advanced) +# Configuring Babel (Advanced) Most people can get by using Babel with just the built-in presets, but Babel exposes much finer-grained power than that. -## Manually specifying plugins +## Manually specifying plugins Babel presets are simply collections of pre-configured plugins, if you want to do something differently you manually specify plugins. This works almost exactly the same way as presets. @@ -534,7 +534,7 @@ For a full list of official plugins see the [Babel Plugins page](http://babeljs. Also take a look at all the plugins that have been [built by the community](https://www.npmjs.com/search?q=babel-plugin). If you would like to learn how to write your own plugin read the [Babel Plugin Handbook](plugin-handbook.md). -## Plugin options +## Plugin options Many plugins also have options to configure them to behave differently. For example, many transforms have a "loose" mode which drops some spec behavior in favor of simpler and more performant generated code. @@ -551,7 +551,7 @@ To add options to a plugin, simply make the following change: > I'll be working on updates to the plugin documentation to detail every option in the coming weeks. [Follow me for updates](https://twitter.com/thejameskyle). -## Customizing Babel based on environment +## Customizing Babel based on environment Babel plugins solve many different tasks. Many of them are development tools that can help you debugging your code or integrate with tools. There are also a lot of plugins that are meant for optimizing your code in production. @@ -594,7 +594,7 @@ $ [COMMAND] > > **Tip:** If you want your command to work across unix and windows platforms then use [`cross-env`](https://www.npmjs.com/package/cross-env). -## Making your own preset +## Making your own preset Manually specifying plugins? Plugin options? Environment-based settings? All this configuration might seem like a ton of repetition for all of your projects. @@ -649,15 +649,15 @@ Then simply publish this to npm and you can use it like you would any preset. * * * -# Babel and other tools +# Babel and other tools Babel is pretty straight forward to setup once you get the hang of it, but it can be rather difficult navigating how to set it up with other tools. However, we try to work closely with other projects in order to make the experience as easy as possible. -## Static analysis tools +## Static analysis tools Newer standards bring a lot of new syntax to the language and static analysis tools are just starting to take advantage of it. -### Linting +### Linting One of the most popular tools for linting is [ESLint](http://eslint.org), because of this we maintain an offical [`babel-eslint`](https://github.com/babel/babel-eslint) integration. @@ -703,11 +703,11 @@ $ npm run lint For more information consult the [`babel-eslint`](https://github.com/babel/babel-eslint) or [`eslint`](http://eslint.org) documentation. -### Code Style +### Code Style JSCS is an extremely popular tool for taking linting a step further into checking the style of the code itself. A core maintainer of both the Babel and JSCS projects ([@hzoo](https://github.com/hzoo)) maintains an official integration with JSCS. -Even better, this integration now lives within JSCS itself under the `--exnext` option. So integrating Babel is as easy as: +Even better, this integration now lives within JSCS itself under the `--esnext` option. So integrating Babel is as easy as: $ jscs . --esnext @@ -729,19 +729,19 @@ For more information consult the [`babel-jscs`](https://github.com/jscs-dev/babe > [WIP] --> -### Documentation +### Documentation Using Babel, ES2015, and Flow you can infer a lot about your code. Using [documentation.js](http://documentation.js.org) you can generate detailed API documentation very easily. Documentation.js uses Babel behind the scenes to support all of the latest syntax including Flow annotations in order to declare the types in your code. -## Frameworks +## Frameworks All of the major JavaScript frameworks are now focused on aligning their APIs around the future of the language. Because of this, there has been a lot of work going into the tooling. Frameworks have the opportunity not just to use Babel but to extend it in ways that improve their users' experience. -### React +### React React has dramatically changed their API to align with ES2015 classes ([Read about the updated API here](http://babeljs.io/blog/2015/06/07/react-on-es6-plus/)). Even further, React relies on Babel to compile it's JSX syntax, deprecating it's own custom tooling in favor of Babel. You can start by setting up the `babel-preset-react` package following the [instructions above](#babel-preset-react). @@ -755,7 +755,7 @@ Most notably the [`babel-plugin-react-transform`](https://github.com/gaearon/bab > [WIP] --> -## Text Editors and IDEs +## Text Editors and IDEs Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your text editor doesn't support it then it can be a really bad experience. For this reason you will want to setup your text editor or IDE with a Babel plugin. @@ -772,7 +772,7 @@ Introducing ES2015, JSX, and Flow syntax with Babel can be helpful, but if your * * * -# Babel Support +# Babel Support Babel has a very large and quickly growing community, as we grow we want to ensure that people have all the resources they need to be successful. So we provide a number of different channels for getting support. @@ -780,11 +780,11 @@ Remember that across all of these communities we enforce a [Code of Conduct](htt We are also looking to grow a self-supporting community, for people who stick around and support others. If you find someone asking a question you know the answer to, take a few minutes and help them out. Try your best to be kind and understanding when doing so. -## Babel Forum +## Babel Forum [Discourse](http://www.discourse.org) has provided us with a hosted version of their forum software for free (and we love them for it!). If forums are your thing please stop by [discuss.babeljs.io](https://discuss.babeljs.io). -## Babel Chat +## Babel Chat Everyone loves [Slack](https://slack.com). If you're looking for immediate support from the community then come chat with us at [slack.babeljs.io](https://slack.babeljs.io). @@ -794,7 +794,7 @@ Everyone loves [Slack](https://slack.com). If you're looking for immediate suppo > [WIP] --> -## Babel Issues +## Babel Issues Babel uses the awesome issue tracker provided by [Phabricator](http://phabricator.org) an open source software development platform that makes GitHub issues a nightmare of the past. @@ -806,7 +806,7 @@ If you want to open a new issue: * [Login](https://phabricator.babeljs.io/auth/start/) or [Create an account](https://phabricator.babeljs.io/auth/register/) (You can also login using GitHub, Facebook, Twitter, Google, etc.) * [Create a new bug report](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-2ufzspoyuk4udiwfnzls#R) or [request a new feature](https://phabricator.babeljs.io/maniphest/task/create/?projects=PHID-PROJ-dfaevtocl5zgjtstjijd#R) -### Creating an awesome Babel bug report +### Creating an awesome Babel bug report Babel issues can sometimes be very difficult to debug remotely, so we need all the help we can get. Spending a few more minutes crafting a really nice bug report can help get your problem solved significantly faster. @@ -816,4 +816,4 @@ First, try isolating your problem. It's extremely unlikely that every part of yo * * * -> ***更多的最新資訊，請上[@thejameskyle](https://twitter.com/thejameskyle)的Twitter查詢。*** \ No newline at end of file +> ***更多的最新資訊，請上[@thejameskyle](https://twitter.com/thejameskyle)的 Twitter 查詢。*** \ No newline at end of file