# braziljs/eloquente-javascript: the Brazilian Portuguese Eloquent JavaScript, built from Markdown

> The BrazilJS community maintains a Portuguese translation of Eloquent JavaScript's 4th edition, with an online HTML build, a PDF and an EPUB. The translation was produced with AI assistance and is explicitly open to community revision, which is the main thing to weigh before assigning it to a reader.

**braziljs/eloquente-javascript** — Tradução do livro "Eloquent JavaScript" 4ª edição, por Marijn Haverbeke

- Repository: https://github.com/braziljs/eloquente-javascript
- Website: http://braziljs.github.io/eloquente-javascript/
- Stars: 5,512 · Forks: 1,210
- Language: JavaScript
- License: not declared
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/braziljs-eloquente-javascript

## A Portuguese edition of Eloquent JavaScript, not a JavaScript library

This repository is a book translation, so the usual adoption questions about runtime, API surface and dependencies do not apply. What it solves is narrower and more concrete: a Brazilian Portuguese reader who wants Marijn Haverbeke's Eloquent JavaScript, 4th edition, without reading 400-plus pages of English. The README states the scope directly, describing the project as a translation into Brazilian Portuguese of the original book at eloquentjavascript.net, and the chapter list runs from Introdução through a Node chapter and a final project on a skill-sharing site. Twenty-two chapters, split into three parts: language, browser, Node.

The audience is the Portuguese-speaking developer learning JavaScript, plus instructors who want assigned reading in the students' own language. The README is candid about provenance in a way that matters more than the chapter list: the 4th edition was translated with the help of artificial intelligence and is open to community review, with pull requests described as welcome and essential to the text's continued quality. That sentence is the whole adoption decision in miniature. You are not getting a translation that a named human translator signed off on line by line. You are getting a machine-assisted draft that a community is expected to keep correcting.

## Markdown chapters, a Node build pipeline, and generated HTML, PDF and EPUB

The repository layout is the mechanism. At the top level sit numbered Markdown files, 00_intro.md through 21_skillsharing.md, one per chapter. Alongside them are a Makefile, a package.json, and directories for code, docs, epub, img, pdf and src. The docs directory holds the rendered HTML that the online reading link serves, and docs/00_intro.html through docs/21_skillsharing.html mirror the Markdown chapter names.

The Makefile defines the build as a chain of Node scripts. Each chapter HTML file is produced by running src/render_html.mjs on the corresponding Markdown file, then src/build_code.mjs on the same file. A separate step, src/chapter_info.mjs, generates html/code/chapter_info.js from every chapter plus the files under code/solutions. The interactive code editor in the browser is bundled by rollup from a config at src/client/rollup.config.mjs, pulling in CodeMirror packages, acorn and acorn-walk listed in package.json. The all target is the full artifact set: html, book.pdf, book_mobile.pdf, book.epub and book.mobi.

The code examples are not decorative. The Makefile's test target renders the HTML first, then loops over every chapter running node src/run_tests.mjs on it, and finishes with node src/check_links.mjs. That means the book's sample programs are executed as part of the build, and broken links fail the run. For a translated text where code blocks could drift from the English source, that check is the most useful thing in the repository.

## Reading it online, or building the PDF and EPUB yourself

Most readers never clone anything. The README gives three direct routes: read it online at braziljs.github.io/eloquente-javascript, download JavaScript_Eloquente.pdf, or download JavaScript_Eloquente.epub from the same host. Those are the fastest paths and they require no toolchain.

If you want to build the artifacts locally, the Makefile is the entry point. The default target builds HTML, both PDFs, the EPUB and the MOBI file, so it expects the LaTeX toolchain used under pdf/ as well as Node. For a text-only build you can limit yourself to the html target. Install dependencies first, then run the build:

```bash
npm install
make html
```

The html target writes rendered chapter files into html/, runs the code bundler, and zips the skill-sharing project and one of the exercise solutions. After it completes you should see html/00_intro.html alongside the rest of the chapter files, plus html/ejs.js. To check that the sample code in the chapters still runs, the test target is what you want:

```bash
make test
```

The Makefile prints a Testing line per chapter, then runs the link checker, then prints Done. Because the test target depends on html, a plain make test rebuilds the HTML first. Expect the run to take a while: it renders every chapter and executes the code inside each one.

## The AI-assisted translation is the limitation you have to price in

The README does not hide it. The 4th edition was translated with artificial intelligence assistance and is open to community review. For a programming book this shows up in specific places: idiomatic expressions, puns in chapter titles, and the prose around code that explains intent rather than syntax. Machine translation handles a for loop fine. It handles a paragraph explaining why a closure captures a binding less reliably, and that paragraph is usually the part the reader actually needed.

There is a partial mitigation in the repository: a glossario.md file at the top level, which suggests terminology is being tracked rather than improvised per chapter. The README does not describe how the glossary is enforced or whether the build checks that chapter text uses its terms, so treat it as a reference the community maintains, not a guarantee.

A second limitation is structural. The repository is a translation of the 4th edition, and the README points to a preserved 2nd edition branch for historical reference. Nothing in the repository indicates a 5th edition exists or is planned. If you need the newest English material, this translation will lag it by however long the community takes to port a new edition, and there is no stated schedule.

A third point is the licence. package.json declares CC BY-NC 3.0 for the project, and the README links to the Creative Commons BY-NC 3.0 deed. Non-commercial is the constraint that catches people: a training company that wants to print chapters for a paid course is in different territory from a reader opening the web version. The README gives no guidance beyond the licence link, so read the deed itself.

## When the English original is the better choice

The obvious alternative is the original Eloquent JavaScript at eloquentjavascript.net, also by Marijn Haverbeke, also free to read online. The difference in approach is not a feature list, it is authorship: the English text is the source, written by the author, and this repository is a derivative translation of it. Every ambiguity in this project resolves by consulting the original, which means a reader who can read English gains nothing from the Portuguese edition except speed.

The case for this repository is the reader who cannot comfortably read English technical prose. For them the comparison is not original versus translation, it is translation versus nothing, and a machine-assisted Portuguese draft that runs its own code examples is clearly better than no Portuguese text at all. The case against is narrower but real: anyone who needs precise, citable terminology, or who is teaching and will be asked why a sentence reads oddly. Then the original is the safer source and this repository is a second opinion.

There is also the question of whether the 4th edition is the one you want. The README lists a 2nd edition branch kept for historical reference, so older readers may find the edition they remember there. The related searches around the book include requests for a 3rd edition PDF and speculation about a 5th, which suggests readers arrive looking for a specific edition and are not always sure which one this repository carries. It carries the 4th.

## Maintenance, cost and what the build actually asks of you

The repository is not archived, and the last push was on 2026-08-04, which is recent enough that the project is being touched. That is the only maintenance signal in the repository. There are no retrieved releases, so there is no versioned artifact to pin and no changelog to read. The package.json version is 0.1.0 and describes the build tooling rather than the book, so it tells you nothing about how finished the translation is.

The upgrade cost is mostly your own environment. Building the full artifact set means Node plus whatever the pdf/build.sh script under pdf/ needs, since the book.pdf target shells out to it. The truncated Makefile shows the book.pdf rule invoking sh build.sh bo from inside pdf/, and the tex target generating .tex files per chapter plus converting SVG images to PDF under img/generated. If you only need HTML, you skip all of that. If you need the EPUB, the all target is the path, and it drags the PDF toolchain along with it.

Licence implications are straightforward to state and hard to overstate: CC BY-NC 3.0 permits sharing and adaptation with attribution but not commercial use. The README attributes the original author and the BrazilJS community translation, and the package.json carries the same licence string. If your use is commercial, the licence is the blocker, not the translation quality.

## Conclusion

Adopt it if you want a Portuguese reading path through Eloquent JavaScript and you are willing to read past machine-translated phrasing. Do not adopt it as a citable reference for terminology without checking glossario.md, and do not treat the EPUB or PDF as a fixed artifact: they are build outputs from the Markdown chapters. Verify the specific chapter you care about against the English original before you put it in front of students.

## FAQ

### Is Eloquent JavaScript free to read?

Yes. The README links to an online version at braziljs.github.io/eloquente-javascript and offers direct PDF and EPUB downloads from the same site, with no payment step described.

### What is Eloquent JavaScript about?

It is an introduction to JavaScript, programming and the browser, split into three parts covering the language, the browser and Node.js, ending with a project on a skill-sharing site.

### Is Eloquent JavaScript a good book?

The repository does not evaluate the book's quality, but it does state that the 4th edition translation was produced with AI assistance and is open to community review, so the Portuguese text is a draft under correction rather than a finished edition.

## Sources

- [braziljs/eloquente-javascript on GitHub](https://github.com/braziljs/eloquente-javascript)
- [Issues](https://github.com/braziljs/eloquente-javascript/issues)
- [Project website](http://braziljs.github.io/eloquente-javascript/)
- [README](https://github.com/braziljs/eloquente-javascript/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/braziljs-eloquente-javascript