How to Help Translate the Free Programming Books Repository Documentation

You can help translate the Free Programming Books repository documentation by creating or updating language-specific Markdown files in the docs/ folder, following the MARC relator syntax for crediting translators, and ensuring your changes pass the automated fpb-lint checks via pull request.

The Free Programming Books repository relies on community volunteers to maintain documentation in multiple languages. If you want to help translate the repository's documentation, you will work with structured Markdown files under the docs/ directory and adhere to strict formatting guidelines enforced by continuous integration.

Understanding the Translation Architecture

All translation-related documentation lives under the docs/ folder. This directory serves as the central hub for localized versions of contribution guidelines and instructional content.

The docs/README.md file functions as the primary entry point, containing a comprehensive table of every language that maintains translated documentation sets. When beginning a translation effort, consult this file to determine whether your target language already exists or requires a new entry.

The docs/CONTRIBUTING.md file contains the definitive "Translating" section, which mandates the use of MARC relators for author attribution and specifies strict Markdown formatting rules that must remain consistent across all languages. Additionally, docs/HOWTO.md provides step-by-step contribution workflows, with language-specific variants (such as docs/HOWTO-zh.md for Chinese) derived directly from this master document.

Step-by-Step Translation Workflow

1. Select Your Target Language

Open docs/README.md and locate the language table. If your language already appears, identify which specific files need updates. If your language is absent, you will create new files following the naming convention HOWTO-<lang>.md, CONTRIBUTING-<lang>.md, and similar variants, where <lang> represents the ISO language code.

2. Translate Core Documentation Files

Copy the English source from docs/HOWTO.md or docs/CONTRIBUTING.md as your base template. Translate the text while preserving the original Markdown structure, including heading levels, bullet point indentation, and link syntax. Do not alter link URLs or modify the formatting rules described in the Formatting section of CONTRIBUTING.md.

3. Credit Creators Using MARC Relators

When translating resource entries in the books/ directory files (such as books/free-programming-books-es.md for Spanish), you must credit both original authors and translators using MARC relator codes. Append the translator credit using the trl.: prefix immediately after the author name.

* [Guía Traducida](https://example.org/guia.html) - María Gómez, `trl.:` Ana Silva (HTML)

For standard entries without translation credits, maintain the exact spacing rules: a single space, hyphen, space (-) before the author, and format/license details in parentheses.

* [Libro de Ejemplo (2021)](https://example.org/libro.pdf) - Juan Pérez (PDF) (CC BY-SA)

4. Validate with the Local Linter

The repository includes a continuous integration workflow defined in .github/workflows/fpb-lint.yml that automatically checks for alphabetical ordering, Markdown formatting consistency, and URL validity. You can run these same checks locally before submitting to ensure compliance.

Install dependencies and execute the linter using the script defined in package.json:

# Install dependencies (run once)

npm ci

# Run the fpb-lint checks on all Markdown files

npm run lint

If the command completes without errors, your changes satisfy the repository's automated quality gates.

5. Submit via Pull Request

Push your translated files to a forked repository and open a Pull Request. The GitHub Actions workflow will automatically execute the awesome_bot URL validator and formatting checks. If the CI reports failures, edit the files to resolve alphabetical ordering issues or broken links, then push the corrections; the workflow will re-run automatically.

Formatting Rules for Translated Content

Successful translations must obey three strict structural requirements defined in the source code.

Maintain Markdown Structure. All headings, bullet points, and link syntax must remain identical to the English source files. Do not convert bullet lists to numbered lists or alter heading hierarchy.

Preserve Alphabetical Ordering. The fpb-lint tool enforces strict alphabetical ordering within all list files. Translated entries must insert into the existing sequence based on the translated title, not appended to the end of the file.

Use Exact Spacing Conventions. Author credits require a single space, hyphen, space (-) delimiter. Format indicators (such as (PDF) or (HTML)) and license tags (such as (CC BY-SA)) must appear in parentheses with single spaces separating multiple tags.

Summary

• Repository structure: Translation files reside in docs/ with language-specific variants named using ISO codes (e.g., HOWTO-zh.md).
• Attribution syntax: Use MARC relator trl.: to credit translators immediately after original authors in book list entries.
• Quality assurance: The .github/workflows/fpb-lint.yml CI workflow checks alphabetical ordering, Markdown formatting, and URL health on every pull request.
• Local validation: Run npm run lint locally after executing npm ci to verify your changes before submission.
• Content scope: Translate documentation in docs/ and resource entries in books/free-programming-books-<lang>.md while preserving exact Markdown structure and spacing.

Frequently Asked Questions

What files should I translate first?

Start with docs/HOWTO.md and docs/CONTRIBUTING.md, as these provide the essential contribution guidelines for speakers of your target language. Check docs/README.md to see if language-specific variants already exist; if they do, update those files rather than creating duplicates.

How do I properly credit a translator in the book lists?

Append the translator's name after the original author using the MARC relator code trl.: enclosed in backticks. The exact syntax is `trl.:` Name placed immediately after the author name and comma, before the format and license parentheses. Refer to the Creators section in docs/CONTRIBUTING.md for complete examples.

Can I translate the book lists themselves or just the documentation?

You can and should translate both. The docs/ folder contains procedural documentation (HOWTO guides), while the books/ directory contains the actual resource lists (such as books/free-programming-books-es.md). Both require translation to fully support a language community, and both must follow identical formatting and attribution rules.

What happens if the CI checks fail on my translation PR?

The fpb-lint workflow will block merging until all checks pass. Common failures include incorrect alphabetical ordering, malformed Markdown syntax, or dead URLs. Review the GitHub Actions logs to identify specific file and line errors, correct the issues locally, commit the changes, and push to your branch; the CI will automatically re-evaluate the updated pull request.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}