Simplest Bitcoin Book Translation Tool

A Python toolkit for translating and managing the Simplest Bitcoin Book across multiple languages using Google's Gemini AI.

Complete Workflow

1. TRANSLATE      2. COMBINE           3. HUMAN REVIEW        4. FIX FORMATTING
   (chapters)        (into one file)      (Google Docs)          (restore markdown)
       │                  │                    │                       │
       ▼                  ▼                    ▼                       ▼
   swahili/        full_language_books/  reviewed_full_language_books/  final_full_language_books/
   ├── 01-.../     └── Swahili_Book.md   └── Swahili_Book.md            └── Swahili_Book_Fixed.md
   ├── 02-.../         (original)            (human edits)                  (final output)
   └── ...

Directory	Purpose
full_language_books/	Machine-translated combined books (original formatting)
reviewed_full_language_books/	Human-edited versions from Google Docs (broken formatting)
final_full_language_books/	Final output with human edits + restored formatting

What it does

• Translates all .md files in a directory to any language
• Keeps all Markdown formatting intact (headers, links, code blocks, etc.)
• Copies non-markdown files as-is
• Maintains directory structure
• Translates code comments but leaves code unchanged

Installation

1. Install Python

Make sure you have Python 3.7+ installed on your computer.

2. Install required packages

pip install google-genai pathlib

3. Get a Gemini API key

1. Go to Google AI Studio
2. Create a new API key
3. Copy the key (you'll need it in step 4)

4. Set up your API key

On Windows:

set GEMINI_API_KEY=your_api_key_here

On Mac/Linux:

export GEMINI_API_KEY=your_api_key_here

How to use

Basic usage

python gemini_translation_script.py source_folder target_language

Examples

# Translate English docs to Spanish
python gemini_translation_script.py english spanish

# Translate docs to French
python gemini_translation_script.py my_docs french

# Translate to any language
python gemini_translation_script.py content "simplified chinese"

Advanced options

# Specify source language (default is English)
python gemini_translation_script.py docs spanish --source_language english

# Use a different AI model
python gemini_translation_script.py docs french --model_name gemini-2.0-flash-001

# Overwrite existing files without asking
python gemini_translation_script.py docs spanish --force_overwrite

File structure

Before translation:

project/
├── english/
│   ├── intro.md
│   ├── guide.md
│   └── images/
│       └── screenshot.png
└── gemini_translation_script.py

After running: python gemini_translation_script.py english spanish

project/
├── english/
│   ├── intro.md
│   ├── guide.md
│   └── images/
│       └── screenshot.png
├── spanish/
│   ├── intro.md          ← Translated!
│   ├── guide.md          ← Translated!
│   └── images/
│       └── screenshot.png ← Copied as-is
└── gemini_translation_script.py

What gets translated

✅ Translates:

• Text content in Markdown files
• Headings and paragraphs
• List items
• Table content
• Code comments
• Alt text for images

❌ Keeps unchanged:

• File names
• Folder names
• URLs and links
• Image file paths
• Code (except comments)
• Non-markdown files

Troubleshooting

"API key not set" error

Make sure you've set the GEMINI_API_KEY environment variable correctly.

"Translation blocked" messages

Some content might be blocked by safety filters. The original text will be kept with a warning message.

"Permission denied" errors

Make sure you have write permissions in the target directory.

Files already exist

The script will ask before overwriting files. Use --force_overwrite to skip confirmations.

Tips

• Test with a small folder first
• Review translations for accuracy
• Keep backups of your original files
• Use descriptive language names (e.g., "spanish" instead of "es")

Supported languages

You can translate to any language that Gemini supports. Use natural language names:

• spanish, french, german, italian
• chinese, japanese, korean
• portuguese, russian, arabic
• hindi, bengali, turkish
• And many more!

Need help?

If you encounter issues:

1. Check that your API key is set correctly
2. Make sure you have an internet connection
3. Verify the source directory exists and contains .md files
4. Try with a smaller test directory first

Combining Chapters into a Single File

The combine_language_chapters.py script can be used to merge all chapter index.md files from a specific language folder (located in the project root) into a single Markdown document. This is useful for creating a full-text version of the book in a given language.

How to use combine_language_chapters.py

Basic usage:

python combine_language_chapters.py <language_folder_name> <output_markdown_filename>

Arguments:

• <language_folder_name>: The name of the language folder in your project root (e.g., english, swahili, french). This folder should contain subdirectories for each chapter (e.g., 01-why-we-need/, 02-bitcoin-fixes-this/), each with an index.md file.
• <output_markdown_filename>: The desired name for the combined Markdown file (e.g., Swahili_FullBook.md).

Examples:

# Combine all chapters from the 'swahili' folder into 'Swahili_Book.md'
python combine_language_chapters.py swahili Swahili_Book.md

# Combine all chapters from the 'english' folder into 'English_Complete.md'
python combine_language_chapters.py english English_Complete.md

Advanced options:

# Specify a different source base directory (if language folders are not in the current dir)
python combine_language_chapters.py swahili Swahili_Book.md --source_base_dir path/to/language_folders/

# Change the Markdown heading level for chapter titles (default is 1 for H1)
python combine_language_chapters.py french French_Book.md --title_level 2

What the script does:

• Looks for a language folder (e.g., swahili/) in the specified source base directory (defaults to the current directory).
• Finds all chapter subfolders (e.g., 01-some-topic/, 02-another-topic/) within that language folder.
• Sorts these chapter folders alphanumerically.
• For each chapter folder:
  • Derives a chapter title from the folder name (e.g., "01-Why We Need" becomes "Why We Need").
  • Reads the index.md file from the chapter folder.
  • Strips any existing YAML frontmatter from this index.md.
  • Prepends the derived chapter title as a Markdown heading (default H1).
  • Appends the chapter's content to the combined output.
• Saves the complete combined content to the specified output file.

Repairing Google-Docs-Edited Chapters

When collaborators edit in Google Docs, Markdown formatting and image tags get stripped. The chapter_fixer.py script merges human edits with proper formatting.

Usage

1. Export your reviewed book from Google Docs and save to reviewed_full_language_books/
2. Run the fixer:

python chapter_fixer.py full_language_books/Swahili_Book.md reviewed_full_language_books/Swahili_Book.md final_full_language_books/Swahili_Book_Fixed.md

The script will:

• Keep all human text edits from the reviewed version
• Restore Markdown formatting from the original
• Re-insert all image tags in correct positions

Google Docs Drafts For Review

Simplest Bitcoin Book Translations 1: This document contains full book translations in Swahili, Luganda, French, Yoruba, Hindi, Russian, Rukiga, Bulgarian, German, Hausa, Zulu, and Italian.

Link: https://docs.google.com/document/d/14Mc0iri-sFQ963Q0ohZCFQMOclYDHQalAilAnTt0M-8/edit?usp=sharing

Simplest Bitcoin Book Translations 2: This document includes full book translations in Bahasa Indonesia, Xhosa, Korean, Japanese, and Mandarin Chinese.

Link: https://docs.google.com/document/d/1qkRmABEflINoaZXRJ-mC_NCAjQlUSq0M4V_3skum1q4/edit?usp=sharing