# How to Update Existing Translations for tldr-pages: Scripts, Workflows, and Validation > Learn to update tldr page translations efficiently. Use Python scripts for synchronization and validation, ensuring accurate and up-to-date documentation across all locales. - Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr) - Tags: how-to-guide - Published: 2026-03-05 --- **Use the Python scripts in `scripts/`—[`set-page-title.py`](https://github.com/tldr-pages/tldr/blob/main/set-page-title.py), [`set-more-info-link.py`](https://github.com/tldr-pages/tldr/blob/main/set-more-info-link.py), [`set-see-also.py`](https://github.com/tldr-pages/tldr/blob/main/set-see-also.py), and [`set-alias-page.py`](https://github.com/tldr-pages/tldr/blob/main/set-alias-page.py)—to synchronize content from English pages into translated versions in `pages./`, 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./` 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`](https://github.com/tldr-pages/tldr/blob/main/pages.fr/common/tar.md). Each translation must adhere to the formatting rules specified in [`contributing-guides/style-guide.md`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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: ```bash 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`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-more-info-link.py). To set a specific link for one language: ```bash 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): ```bash 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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-see-also.py) to synchronize these metadata sections. Update a specific language: ```bash python3 scripts/set-see-also.py -p common/tar -S -l fr ``` Or bulk-update every translation: ```bash 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`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-alias-page.py): ```bash 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.//.md`. **Required format adherence:** - **Title:** `# command_name` (must match filename exactly) - **Description:** One or two lines prefixed with `>` - **More information:** `> More information: .` - **Examples:** Use `{{path/to/file}}` placeholders and **imperative mood** (e.g., "Create an archive," not "Creates an archive") After manual edits, validate formatting: ```bash 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./` 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`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md) ## Frequently Asked Questions ### Where are tldr-pages translation files stored? Translation files follow the pattern `pages.//.md`, where `` 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./` following the specifications in [`contributing-guides/style-guide.md`](https://github.com/tldr-pages/tldr/blob/main/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.