Translating

One of the primary reasons that this site was created was to encourage and support the community in translating books into non-English languages. If you would like to contribute a translation of a book, or even a single chapter, please read to information below.

Steps

Here are the steps to translate content:

1. Leave a comment on the chapter you plan to translate. Include you name and the language you will be translating the content into.
2. Send a quick email to Mike Chambers (mikechambers@gmail.com), and let him know the chapter / content that you plan to translate.
3. Grab the markdown source. This will be linked as "markdown" at the top of the chapter page.
4. The source is returned in an XML file. You should translate the following fields:
   • chapter.title
   • chapter.heading
   • chapter.book.title
   • chapter.book.summary
   • chapter.content
5. Read the information below on the markdown format.
6. Translate the content. All fields are plain text except for the content field, which is in the markdown syntax.
7. All text should be saved as UTF-8.
8. Email the translated content as a file attachment to Mike Chambers (mikechambers@gmail.com). Make sure to include your name, email address and URL.
9. Once the format of the content has been checked, it will be uploaded into the website.

Note that translated content will be posted under the same creative commons license as the content it is based on.

Format

The source of the chapters is stored in the markdown format. Markdown was chosen for a number of reasons, including:

• Simple syntax
• Easy to use
• Outputs to multiple formats
• Human readable
• Easy to Test

In general, when translating content, you should just make sure to use the same formatting and white space of the original document. You can also find a complete syntax reference here.

In addition to the markup provided by markdown, we also use some custom HTML markup. This markup, along with some of the other conventions used, are listed below:

• Inline Links

  <http://www.foo.com>
  	

• Note

  <div class="note">
  	    <div class="note_title">NOTE</div>
  	    Note content here. No markdown markup.
  	</div>
  	

• Table

  <table>
  	    <tr>
  	        <td class="header"></td>
  	        <td class="header"></td>
  	    </tr>
  	    <tr>
  	        <td>
  	        </td>
  	    </tr>
  	</table>
  	

• Commands

  Shows commands or other text that should be typed literally by the user

  **`Constant width bold`**
  	

• User Replaceable Text

  Shows text that should be replaced with user-supplied values

  *`Constant width italic`*
  	

• Inline Code

  Indicates commands, options, switches, variables, attributes, keys, functions, types, classes, namespaces, methods, modules, properties, parameters, values, objects, events, event handlers, XML tags, HTML tags, macros, the contents of files, and the output from commands

  `Constant width`
  	

• Code Block

  See Markdown Syntax reference

• File names and Paths

  Indicates new terms, URLs, email addresses, filenames, file extensions, pathnames, directories, and Unix utilities

  _Italic_
  	

Note that markdown syntax is not processed when inside HTML tags. So, when using Tables or Note DIVs, you must enter all of the relevant HTML (for links, etc..)

You can play around with and test markdown syntax online here.

The TextMate editor on Mac OS X also has built in support for working with Markdown content (Bundles > Markdown).

Leave a Comment