Translation

Eloquent JavaScript's license allows non-commercial translations. That means that you don't sell the result, don't use it to serve ads, and generally don't directly monetize it. If monetization is your goal, talk to my publisher to see if they are willing to enter a commercial translation contract with you.

This is a big book. I get quite a lot of enthusiastic emails from people who are starting a translation. I wrote this wiki page to give those people some pointers, and reduce the chances of their work going to waste. The main principle is: translate in the open, so that other people can help and continue the work if you, for whichever reason, don't finish it.

Step 1: learn git and create a github.com account

If you are a developer, you may already know git. If not: git is a version control tool, which helps you store changes you make to text files, so that you can later go back and see when and why you made those changes. It also makes it very easy to share such changes with other people.

Work on Eloquent JavaScript was (and is) tracked in git, and its github repository contains its whole history. The best way to do a translation is to build from this repository (which also includes the build scripts used to create HTML, PDF, and ePub files), and translate the .txt files that contain the text.

If you need to learn git, I can't recommend a specific tutorial, but there are lots online, so look around, and see which one works for you.

Step 2: publicly fork this repository

Github allows users to fork repositories, that is, to create a copy that they can add additional changes to. Such forks are, by default, public, which means that everybody can see them, and fork them again to do more work on them. This is a good thing. It means that your work can be found, and stays around for other people to use even if you abandon it.

Once you've done this, edit this wiki page and add a link to your fork to the bottom, along with the language that you are translating to.

Step 3: build

Set up a build environment. The README file contains basic instructions on how to install the software you need. Doing make html should produce a readable HTML version of your text in the html subdirectory.

If you're on a windows system, you're probably out of luck, since the build system uses various Unix-specific things. If you're into suffering, you can try installing Cygwin or so, and see if you can get everything running there. But this should probably only to be tried by serious nerds.

If you're stuck on this step, don't worry, just proceed with step 4, and once you have done a bunch of work, write me, and ask me for help. I can set up a thing where you can push (another git term) to my server, and have the HTML built there.

Step 4: translate

Open, for example, 00_intro.txt in your favorite text editor, and translate some of it to your language of choice. The book is written in AsciiDoc, which is a textual format somewhat like Markdown, but more powerful. See the user guide for details. Eloquent JavaScript defines a few extra macros (such as (!interactive foo!) for text that should only appear in the interactive version of the book), but you can probably figure those out from looking at the existing text.

After you've translated a bit, commit your changes with git, and push them to your github repository to make them public. Do this often, at least at the end of every work session, both to keep a record of what you did when, and to make sure no work is lost.

Step 5: publish

Once a translation is finished, talk to me. I'll gladly host it, and link to it from the book's main page.

Translations in progress:

Russian: https://github.com/stonejs/eloquent-javascript-ru

Portuguese (Brazilian): https://github.com/braziljs/eloquente-javascript/

Spanish: https://github.com/hectorip/Eloquent-JavaScript-es

Finished translations:

None yet.