How to Use Translation Templates When Contributing Translated Pages to TLDR

Copy pre-translated snippets from contributing-guides/translation-templates/ and use helper scripts like set-alias-page.py with the -S flag to synchronize translations automatically.

When contributing to the tldr-pages/tldr repository, using translation templates when contributing translated pages ensures consistency across all supported languages and eliminates redundant translation work. These templates provide standardized wording for common sections—such as "More information" links, "See also" mentions, and alias-page boilerplate—that contributors can copy directly into new language files. The repository also provides automation scripts that read the English source and apply the correct locale-specific template through the config.templates[locale] mapping.

Where Translation Templates Live

All translation templates reside in the contributing-guides/translation-templates/ directory. These files contain exact TLDR-Pages markup with placeholders (e.g., {{path/to/file}}) that you replace with language-specific terms.

The key template files include:

• alias-pages.md – Standard wording for alias pages in every supported language
• more-info-link.md – Template for the "More information:" line used across translations
• see-also-mentions.md – Template for the "See also:" section
• common-descriptions.md and common-arguments.md – Reusable text for command descriptions and argument explanations

According to the contributing-guides/style-guide.md, contributors should use these pre-translated templates whenever possible to maintain uniformity.

Manual Template Usage

When creating a new translated page manually, copy the appropriate snippet from the template directory into your target language file. Replace the placeholders with the specific command details while keeping the translated structure intact.

For example, if you are translating a page that requires a "More information" link, you would copy the snippet from more-info-link.md for your specific locale rather than translating the phrase yourself. This guarantees that the wording matches the standardized form used across the entire repository for that language.

Automated Synchronization with Helper Scripts

The repository provides Python scripts in the scripts/ directory that automate the insertion and synchronization of template content. These tools read the English source page, fetch the matching locale template via config.templates[locale], and replace placeholder values automatically.

Synchronizing Alias Pages

The scripts/set-alias-page.py script handles alias page translations. It reads the English alias page, compares it with the locale-specific template, and updates the translation if differences are detected.

# Create a new translated alias page for French (fr)

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

Updating More Information Links

The scripts/set-more-info-link.py script synchronizes the "More information" line across translations using the template defined in config.templates[locale].

# Update the "More information" line in all German translations

scripts/set-more-info-link.py -S -l de

Managing See Also Mentions

The scripts/set-see-also.py script performs the same synchronization for the "See also" section, ensuring that cross-references follow the standardized template for each language.

# Synchronize the "See also" section for Spanish pages only

scripts/set-see-also.py -S -l es

Using the -S flag with any of these scripts synchronizes all existing translations against the current English page and the corresponding template, staging the modified files for commit.

Validation and CI Checks

Before submission, the scripts/check-pr.sh script validates your changes against the templates. Specifically, it compares each translation's "More information" and "See also" sections with the standard templates. If your translation diverges from the template, the CI emits a warning pointing you back to the relevant template file for correction.

This enforcement ensures that even manual edits remain consistent with the global translation standards defined in contributing-guides/translation-templates/.

Summary

• Translation templates live in contributing-guides/translation-templates/ and provide reusable snippets for common page elements like "More information" links and alias boilerplate.
• Manual workflow: Copy the appropriate template snippet and replace placeholders with your language-specific content.
• Automation tools: Use set-alias-page.py, set-more-info-link.py, and set-see-also.py with the -S flag to bulk-synchronize translations using the config.templates[locale] logic.
• Quality control: The check-pr.sh CI script validates translations against templates to catch inconsistencies before merging.
• Style compliance: The contributing-guides/style-guide.md mandates using these templates to reduce duplicated effort and simplify future updates.

Frequently Asked Questions

What are translation templates in TLDR Pages?

Translation templates are pre-written markdown snippets stored in contributing-guides/translation-templates/ that contain standardized translations for common text elements like "More information: ", "See also: ", and alias-page introductions. They use placeholders such as {{path/to/file}} so contributors can simply copy and fill in the blanks rather than translating from scratch.

How do I synchronize existing translations with new template changes?

Run the helper scripts with the -S flag to synchronize all translations against the current English version and the locale-specific template. For example, scripts/set-more-info-link.py -S updates the "More information" line across all languages, while adding -l [locale] restricts the operation to a specific language (e.g., -l de for German).

Where are the translation template files located?

All templates reside under contributing-guides/translation-templates/ in the repository root. Key files include alias-pages.md, more-info-link.md, and see-also-mentions.md, which contain the standardized wording for those specific sections in every supported language.

What happens if my translation doesn't match the template?

The CI validation script scripts/check-pr.sh compares your translation's boilerplate sections against the official templates. If it detects discrepancies in the "More information" or "See also" sections, it will emit a warning that directs you back to the relevant template file, requiring you to align your submission with the standard before the PR can be merged.

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