scripts/set-alias-page.py: Improve sync translations #15389

Zamoca42 · 2024-12-30T15:16:05Z

This PR improves the user experience of the set-alias-page.py script by adding an interactive wizard and refactoring the sync functionality.

Changes

Interactive Wizard

Added interactive wizard for creating alias pages with clear guidance
Improved user interface with colored output for better readability
Added input validation for required fields (title, original command)
Added preview of the page before creation
Added detailed explanations for each input field with examples

Sync Functionality Refactoring

Added SyncConfig and AliasPage dataclasses for better code organization
Improved title and commands extraction from alias pages
Enhanced sync functionality to handle titles in translations
Improved handling of alias patterns across different languages

Before

Required command line arguments for all inputs
No preview of the page before creation
Less structured sync implementation
No validation for required fields

After

Interactive wizard guides users through page creation
Clear preview of the final page with color-coded sections
More maintainable sync implementation using dataclasses
Input validation with clear error messages
Improved handling of alias patterns across different languages

This reverts commit cf7648e.

This reverts commit ecf2dd9.

sebastiaanspeck · 2024-12-30T17:12:46Z

Could you remove the Korean changes? I think you have committed them by accident when testing

sebastiaanspeck

After removing the Korean changes (or moving them to a separate PR), this LGTM!

scripts/set-alias-page.py

Zamoca42 · 2024-12-31T05:21:51Z

Could you remove the Korean changes? I think you have committed them by accident when testing

Let's separate the Korean alias page into a different PR

Co-authored-by: Sebastiaan Speck <[email protected]>

sebastiaanspeck · 2025-01-03T13:05:21Z

Looks a lot better now, minor thing that remains; the title for a page;
pages/common/docker-container-diff.md with # docker container diff copies as # docker container-diff.

I understand these issues were initially out-of-scope of this PR, but I guess it is better to fix it properly now than iterate multiple times with still a "broken" script.

Zamoca42 · 2025-01-03T18:54:51Z

Looks a lot better now, minor thing that remains; the title for a page; pages/common/docker-container-diff.md with # docker container diff copies as # docker container-diff.

I understand these issues were initially out-of-scope of this PR, but I guess it is better to fix it properly now than iterate multiple times with still a "broken" script.

I also think it's better to fix it properly before moving on.
Regarding the title, it is indeed challenging to account for all possible patterns.
For instance, in pages/common/pacman-r.md, the title is # pacman -R,
whereas in pages/common/npm-run-script.md, the title is # npm run-script.

Currently, the title is parsed from the file path, but it might be better to extract it directly from the original alias content instead.

sebastiaanspeck · 2025-01-03T19:09:49Z

Looks a lot better now, minor thing that remains; the title for a page; pages/common/docker-container-diff.md with # docker container diff copies as # docker container-diff.
I understand these issues were initially out-of-scope of this PR, but I guess it is better to fix it properly now than iterate multiple times with still a "broken" script.

I also think it's better to fix it properly before moving on. Regarding the title, it is indeed challenging to account for all possible patterns. For instance, in pages/common/pacman-r.md, the title is # pacman -R, whereas in pages/common/npm-run-script.md, the title is # npm run-script.

Currently, the title is parsed from the file path, but it might be better to extract it directly from the original alias content instead.

Looks a lot better now, minor thing that remains; the title for a page; pages/common/docker-container-diff.md with # docker container diff copies as # docker container-diff.
I understand these issues were initially out-of-scope of this PR, but I guess it is better to fix it properly now than iterate multiple times with still a "broken" script.
Currently, the title is parsed from the file path, but it might be better to extract it directly from the original alias content instead.

I agree, we just need to copy the title just like it exists in pages/. If we are creating a new page, we could add a third optional argument, just like you did with DOCUMENTATION_COMMAND.

sebastiaanspeck · 2025-01-03T19:11:18Z

scripts/_common.py

@@ -309,7 +309,7 @@ def create_argument_parser(description: str) -> argparse.ArgumentParser:

    parser = argparse.ArgumentParser(description=description)
    parser.add_argument(
-        "-p",
+        "-P",


I believe we still can use -p. Explain why not

That's typically because of the documentation command exception of the "osx/g*.md" document in "osx/gsum.md ". If "-p linux sum" is used as an argument, it recognizes "-p" and causes an error.

However, instead of taking title and commands as arguments, we can use "-p" again if you make it into a wizard form

Feel free to modify it, but that feels like a new PR. Let's fix the current issues and then accept this PR for now.

- Change -P/--page option to -p/--page - Remove positional arguments (ORIGINAL_CMD, DOCUMENTATION_CMD) - Add interactive wizard for creating alias pages - Refactor sync functionality with dataclasses (SyncConfig, AliasPage) - Extract title from alias pages for better sync - Update documentation and examples - Improve code formatting and readability - Add detailed prompts with examples for each input field - Show preview of the page before creation

- Update Config dataclass for global script configuration - Move dataclass definitions to top of file - Remove redundant dry_run and language parameters from functions - Update function signatures to use global config

- Refactor AliasPage to use AliasPageContent - Update function signatures to use new dataclass * get_alias_command_in_page returns AliasPageContent * set_alias_page takes AliasPageContent parameter * generate_alias_page_content takes AliasPageContent - Simplify get_english_alias_pages to return list[AliasPage]

sebastiaanspeck · 2025-01-04T11:37:38Z

IMO this PR is going too broad for the initial scope. Please keep it simple for now and introduce new features in a new PR.

- Move templates into Config class as a field * Remove global templates variable * Update all template references to use config.templates - Add pages_dirs to Config class * Remove redundant pages_dirs variable passing * Use config.pages_dirs throughout the code - Move sync_translations logic into main * Remove sync_translations function * Integrate sync logic directly into args.sync block * Simplify code flow for sync operation

- Rename functions and variables * sync -> sync_alias_page_to_locale * existing_page_content -> existing_locale_page_content * locale_page_content -> new_locale_page_content - Remove redundant comments

Zamoca42 · 2025-01-04T12:24:36Z

IMO this PR is going too broad for the initial scope. Please keep it simple for now and introduce new features in a new PR.

There is no new feature here, just add an argument to the title and get it as input.
Changes in sync also separated variable names and functions.

sebastiaanspeck · 2025-01-04T13:43:40Z

IMO this PR is going too broad for the initial scope. Please keep it simple for now and introduce new features in a new PR.

There is no new feature here, just add an argument to the title and get it as input.

Changes in sync also separated variable names and functions.

The three scripts looked almost identical and now they do not anymore. IMO the benefit is minimal ATM. I would prefer fixing the # page-title bug instead of introducing the wizard etc.

Zamoca42 · 2025-01-04T15:35:00Z

The three scripts looked almost identical and now they do not anymore. IMO the benefit is minimal ATM. I would prefer fixing the # page-title bug instead of introducing the wizard etc.

The separation of title and commands from options in prompt_alias_page_info is a deliberate isolation measure to prevent argument parsing bugs. If these were added as positional arguments, titles like pacman -S would be incorrectly interpreted as options, causing errors. The wizard interface simply serves as an additional guide for input.

For example:

Safe (current): Wizard prompts for "pacman -S" as title
Unsafe (if positional): python3 scripts/set-alias-page.py -p linux/pacman-s "pacman -S" "pacman --sync" "pacman sync" would treat -S and --sync as an option flag

sebastiaanspeck · 2025-01-04T16:21:51Z

The three scripts looked almost identical and now they do not anymore. IMO the benefit is minimal ATM. I would prefer fixing the # page-title bug instead of introducing the wizard etc.

The separation of title and commands from options in prompt_alias_page_info is a deliberate isolation measure to prevent argument parsing bugs. If these were added as positional arguments, titles like pacman -S would be incorrectly interpreted as options, causing errors. The wizard interface simply serves as an additional guide for input.

For example:

Safe (current): Wizard prompts for "pacman -S" as title

Unsafe (if positional): python3 scripts/set-alias-page.py -p linux/pacman-s "pacman -S" "pacman --sync" "pacman sync" would treat -S and --sync as an option flag

Fine by me, but change it for all scripts then to keep them sort-of in sync with each other.

scripts/set-alias-page.py

sebastiaanspeck · 2025-01-04T18:39:40Z

scripts/set-alias-page.py


    target_paths = []

    # Use '--page' option
    if args.page != "":
-        target_paths += get_target_paths(args.page, pages_dirs)
+        page_info = prompt_alias_page_info(args.page)
+        target_paths += get_target_paths(args.page, config.pages_dirs)


This is not working for creating new alias pages. It can only update current alias pages.

scripts/_common.py

def get_target_paths(page: Path, pages_dirs: Path) -> list[Path]: """ Get all paths in all languages that match the page. Parameters: page (Path): the page to search for. Returns: list (list of Path's): A list of Path's. """ target_paths = [] if not page.lower().endswith(".md"): page = f"{page}.md" arg_platform, arg_page = page.split("/") for pages_dir in pages_dirs: page_path = pages_dir / arg_platform / arg_page if not page_path.exists(): continue # Skip if page is missing target_paths.append(page_path) target_paths.sort() return target_paths

Looking at these files, I noticed that 8 months ago there was a change to prevent creating new pages. The change was in get_target_paths() where it skips paths that don't exist.
Is there a specific reason for this change?
From my understanding, the other scripts are designed to modify existing pages

Co-authored-by: Sebastiaan Speck <[email protected]>

tldr-bot · 2025-01-06T07:33:55Z

The build for this PR failed with the following error(s):

would reformat /home/runner/work/tldr/tldr/scripts/set-alias-page.py

Oh no! 💥 💔 💥
1 file would be reformatted, 6 files would be left unchanged.

Please fix the error(s) and push again.

Zamoca42 added 5 commits December 30, 2024 21:21

Update set alias page when file already exists

e94501a

Update Korean translation alias pages

cf7648e

Revert "Update Korean translation alias pages"

b7895f8

This reverts commit cf7648e.

Update original command

f21edaf

Add Korean translation for alias pages

ecf2dd9

Zamoca42 requested review from sebastiaanspeck, kbdharun, IMHOJEONG and CodePsy-2001 as code owners December 30, 2024 15:16

github-actions bot added documentation Issues/PRs modifying the documentation. tooling Helper tools, scripts and automated processes. translation Issues requesting translating pages from English to other languages. labels Dec 30, 2024

Zamoca42 added 4 commits December 31, 2024 00:34

Revert "Add Korean translation for alias pages"

a2394f3

This reverts commit ecf2dd9.

Improve alias page template processing

6e641be

Add Korean translation for alias pages

7138ad6

Update format of alias pages

4ca4c90

This comment was marked as off-topic.

Sign in to view

Zamoca42 added 3 commits December 31, 2024 01:18

Update format of alias pages

56a6cfc

Reformat scripts/set-alias-page.py

14d4685

Merge branch 'main' into update-set-alias-page

5ef6671

sebastiaanspeck changed the title ~~scripts/set-alias-page.py: Fix status message in set-alias-page.py for existing files~~ scripts/set-alias-page.py: Fix status message for existing files Dec 31, 2024

sebastiaanspeck approved these changes Dec 31, 2024

View reviewed changes

sebastiaanspeck requested changes Dec 31, 2024

View reviewed changes

scripts/set-alias-page.py Show resolved Hide resolved

Zamoca42 added 4 commits December 31, 2024 14:33

Remove Korean alias pages

004a9a5

Reverting Korean alias pages template

34733d9

Restore regex for alias page parsing

35f8fc8

Merge branch 'main' into update-set-alias-page

1e8d78e

Zamoca42 removed the translation Issues requesting translating pages from English to other languages. label Dec 31, 2024

Zamoca42 and others added 4 commits January 3, 2025 19:07

Update scripts/set-alias-page.py

5adeab7

Co-authored-by: Sebastiaan Speck <[email protected]>

Update scripts/set-alias-page.py

ee9665f

Co-authored-by: Sebastiaan Speck <[email protected]>

Update scripts/set-alias-page.py

538d1f4

Co-authored-by: Sebastiaan Speck <[email protected]>

Update page only when documentation command changes

60252c4

Merge branch 'main' into update-set-alias-page

9f3dc8a

sebastiaanspeck reviewed Jan 3, 2025

View reviewed changes

Zamoca42 added 3 commits January 4, 2025 17:36

Merge branch 'main' into update-set-alias-page

f373f3d

Update script file documents

b496d9d

Zamoca42 changed the title ~~scripts/set-alias-page.py: fix status message for existing files~~ scripts/set-alias-page.py: Improve sync translations Jan 4, 2025

Zamoca42 added 3 commits January 4, 2025 18:33

Rename command to page_path for clarity

c904cd3

Refactor to use global Config

91ae2ca

- Update Config dataclass for global script configuration - Move dataclass definitions to top of file - Remove redundant dry_run and language parameters from functions - Update function signatures to use global config

Zamoca42 added 2 commits January 4, 2025 20:58

Rename functions and variables for clarity

2f4391f

- Rename functions and variables * sync -> sync_alias_page_to_locale * existing_page_content -> existing_locale_page_content * locale_page_content -> new_locale_page_content - Remove redundant comments

sebastiaanspeck reviewed Jan 4, 2025

View reviewed changes

Update scripts/set-alias-page.py

b643eb6

Co-authored-by: Sebastiaan Speck <[email protected]>

Zamoca42 added 4 commits January 6, 2025 16:43

Add check_exists flag to get_target_paths()

a123833

Update docstring indentation

c81ea1f

Merge branch 'main' into update-set-alias-page

6573a77

Update prompt with page status and documentation

28602dc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

scripts/set-alias-page.py: Improve sync translations #15389

scripts/set-alias-page.py: Improve sync translations #15389

Zamoca42 commented Dec 30, 2024 •

edited

Loading

This comment was marked as off-topic.

sebastiaanspeck commented Dec 30, 2024

sebastiaanspeck left a comment

Zamoca42 commented Dec 31, 2024

sebastiaanspeck commented Jan 3, 2025 •

edited

Loading

Zamoca42 commented Jan 3, 2025 •

edited

Loading

sebastiaanspeck commented Jan 3, 2025

sebastiaanspeck Jan 3, 2025

Zamoca42 Jan 4, 2025

Zamoca42 Jan 4, 2025

sebastiaanspeck Jan 4, 2025

sebastiaanspeck commented Jan 4, 2025

Zamoca42 commented Jan 4, 2025

sebastiaanspeck commented Jan 4, 2025

Zamoca42 commented Jan 4, 2025 •

edited

Loading

sebastiaanspeck commented Jan 4, 2025

sebastiaanspeck Jan 4, 2025

Zamoca42 Jan 6, 2025 •

edited

Loading

tldr-bot commented Jan 6, 2025

scripts/set-alias-page.py: Improve sync translations #15389

Are you sure you want to change the base?

scripts/set-alias-page.py: Improve sync translations #15389

Conversation

Zamoca42 commented Dec 30, 2024 • edited Loading

Changes

Interactive Wizard

Sync Functionality Refactoring

Before

After

This comment was marked as off-topic.

sebastiaanspeck commented Dec 30, 2024

sebastiaanspeck left a comment

Choose a reason for hiding this comment

Zamoca42 commented Dec 31, 2024

sebastiaanspeck commented Jan 3, 2025 • edited Loading

Zamoca42 commented Jan 3, 2025 • edited Loading

sebastiaanspeck commented Jan 3, 2025

sebastiaanspeck Jan 3, 2025

Choose a reason for hiding this comment

Zamoca42 Jan 4, 2025

Choose a reason for hiding this comment

Zamoca42 Jan 4, 2025

Choose a reason for hiding this comment

sebastiaanspeck Jan 4, 2025

Choose a reason for hiding this comment

sebastiaanspeck commented Jan 4, 2025

Zamoca42 commented Jan 4, 2025

sebastiaanspeck commented Jan 4, 2025

Zamoca42 commented Jan 4, 2025 • edited Loading

sebastiaanspeck commented Jan 4, 2025

sebastiaanspeck Jan 4, 2025

Choose a reason for hiding this comment

Zamoca42 Jan 6, 2025 • edited Loading

Choose a reason for hiding this comment

tldr-bot commented Jan 6, 2025

Zamoca42 commented Dec 30, 2024 •

edited

Loading

sebastiaanspeck commented Jan 3, 2025 •

edited

Loading

Zamoca42 commented Jan 3, 2025 •

edited

Loading

Zamoca42 commented Jan 4, 2025 •

edited

Loading

Zamoca42 Jan 6, 2025 •

edited

Loading