How to Update Existing Translations for tldr-pages: Scripts, Workflows, and Validation

Use the Python scripts in scripts/—set-page-title.py, set-more-info-link.py, set-see-also.py, and set-alias-page.py—to synchronize content from English pages into translated versions in pages.<locale>/, then validate changes with npm run lint-tldr-pages.

The tldr-pages project stores command-line cheat sheets in multiple languages. When the English source pages in pages/ are modified, corresponding files in language-specific directories like pages.fr/ or pages.zh/ require updates to maintain accuracy and consistency.

Understanding the Translation Directory Structure

Translations reside in directories named pages.<locale>/ that mirror the structure of the main pages/ folder. For example, the French translation of the tar command is located at pages.fr/common/tar.md. Each translation must adhere to the formatting rules specified in contributing-guides/style-guide.md.

Updating Page Titles with set-page-title.py

When an English page title changes, use scripts/set-page-title.py to propagate that change. This script reads the first line from the English source and rewrites the translation's title line while preserving any placeholders.

Run the following to sync the French translation of the tar page:

python3 scripts/set-page-title.py -p common/tar -S -l fr

Key parameters:

• -p – platform and command path (e.g., common/tar or linux/ls)
• -S – sync mode, pulling the title from the English page
• -l – target language code (e.g., fr, zh, pt_BR)

Alternatively, manually edit the file and modify the line beginning with #, ensuring the command name exactly matches the filename.

Synchronizing More Information Links

The "More information" line follows the description block in every tldr page. Update this across translations using scripts/set-more-info-link.py.

To set a specific link for one language:

python3 scripts/set-more-info-link.py -p common/tar https://example.com -l fr

To sync the English link to all translations (recommended when the source link changes):

python3 scripts/set-more-info-link.py -S

The script inserts the line immediately after the description block using the template from contributing-guides/translation-templates/more-info-link.md to maintain consistent formatting.

Updating See Also Sections

The process for "See also" sections mirrors the more-information workflow. Use scripts/set-see-also.py to synchronize these metadata sections.

Update a specific language:

python3 scripts/set-see-also.py -p common/tar -S -l fr

Or bulk-update every translation:

python3 scripts/set-see-also.py -S

Maintaining Alias Pages with set-alias-page.py

Alias pages are thin wrappers that redirect to another command. Keep these consistent across languages using scripts/set-alias-page.py:

python3 scripts/set-alias-page.py -p common/vi -S -l fr

This script rewrites the alias page according to the English source, stripping any language-specific examples that may have diverged from the standard format.

Manual Editing and Validation

For content changes that scripts cannot handle, edit files directly in pages.<locale>/<platform>/<command>.md.

Required format adherence:

• Title: # command_name (must match filename exactly)

• Description: One or two lines prefixed with >

• More information: > More information: <https://url>.

• Examples: Use {{path/to/file}} placeholders and imperative mood (e.g., "Create an archive," not "Creates an archive")

After manual edits, validate formatting:

npm run lint-tldr-pages

This command checks compliance with the style guide, catching issues like missing newlines, incorrect indentation, or malformed placeholders.

Summary

• Translations live in pages.<locale>/ directories that mirror the English pages/ structure
• set-page-title.py syncs titles using the -S flag and -l language code
• set-more-info-link.py and set-see-also.py update metadata sections across single or all languages
• set-alias-page.py standardizes alias page formatting by referencing English sources
• Always run npm run lint-tldr-pages after edits to ensure compliance with contributing-guides/style-guide.md

Frequently Asked Questions

Where are tldr-pages translation files stored?

Translation files follow the pattern pages.<locale>/<platform>/<command>.md, where <locale> is a language code like fr, zh, or pt_BR. These directories replicate the folder structure of the main pages/ directory containing English content.

Can I update translations without using the Python scripts?

Yes. You can manually edit any .md file in pages.<locale>/ following the specifications in contributing-guides/style-guide.md. However, the scripts ensure consistency with English sources and reduce the risk of formatting errors that would fail the linter.

How do I validate my translation changes before submitting?

Run npm run lint-tldr-pages from the repository root. This linter checks for proper title syntax, correct placeholder formatting, required blank lines between examples, and compliance with the project's markdown standards.

What is the fastest way to update all translations when an English page changes?

Use the -S sync flag without specifying a language to apply changes globally. For example, python3 scripts/set-more-info-link.py -S updates the "More information" link across all available language directories, while python3 scripts/set-page-title.py -p common/command -S updates titles for all translations of that specific command.

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