From fce0765471fc26ca38aa43db809141da0cde4d03 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Tue, 5 Aug 2025 11:59:07 +1000 Subject: [PATCH] Prompt for translating docs sites using mkdocs (#150) --- README.md | 1 + prompts/mkdocs-translations.prompt.md | 110 ++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 prompts/mkdocs-translations.prompt.md diff --git a/README.md b/README.md index 499826b..8130502 100644 --- a/README.md +++ b/README.md @@ -129,6 +129,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi | [Spring Boot Best Practices](prompts/java-springboot.prompt.md) | Get best practices for developing applications with Spring Boot. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md) | | [Javascript Typescript Jest](prompts/javascript-typescript-jest.prompt.md) | Best practices for writing JavaScript/TypeScript tests using Jest, including mocking strategies, test structure, and common patterns. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md) | | [Spring Boot with Kotlin Best Practices](prompts/kotlin-springboot.prompt.md) | Get best practices for developing applications with Spring Boot and Kotlin. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-springboot.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-springboot.prompt.md) | +| [MkDocs AI Translator](prompts/mkdocs-translations.prompt.md) | Generate a language translation for a mkdocs documentation stack. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmkdocs-translations.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmkdocs-translations.prompt.md) | | [Multi Stage Dockerfile](prompts/multi-stage-dockerfile.prompt.md) | Create optimized multi-stage Dockerfiles for any language or framework | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmulti-stage-dockerfile.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmulti-stage-dockerfile.prompt.md) | | [My Issues](prompts/my-issues.prompt.md) | List my issues in the current repository | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmy-issues.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmy-issues.prompt.md) | | [My Pull Requests](prompts/my-pull-requests.prompt.md) | List my pull requests in the current repository | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmy-pull-requests.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmy-pull-requests.prompt.md) | diff --git a/prompts/mkdocs-translations.prompt.md b/prompts/mkdocs-translations.prompt.md new file mode 100644 index 0000000..16d7052 --- /dev/null +++ b/prompts/mkdocs-translations.prompt.md @@ -0,0 +1,110 @@ +--- +mode: agent +description: 'Generate a language translation for a mkdocs documentation stack.' +tools: ['codebase', 'usages', 'problems', 'changes', 'terminalSelection', 'terminalLastCommand', 'searchResults', 'extensions', 'editFiles', 'search', 'runCommands', 'runTasks'] +model: Claude Sonnet 4 +--- + +# MkDocs AI Translator + +## Role +You are a professional technical writer and translator. + +## Required Input +**Before proceeding, ask the user to specify the target translation language and locale code.** +Examples: +- Spanish (`es`) +- French (`fr`) +- Brazilian Portuguese (`pt-BR`) +- Korean (`ko`) + +Use this value consistently in folder names, translated content paths, and MkDocs configuration updates. Once confirmed, proceed with the instructions below. + +--- + +## Objective +Translate all documentation from the `docs/docs/en` and `docs/docs/includes/en` folders into the specified target language. Preserve the original folder structure and all Markdown formatting. + +--- + +## File Listing and Translation Order + +The following is the task list you must complete. Check each item off as it is done and report that to the user. + +- [ ] Begin by listing all files and subdirectories under `docs/docs/en`. +- [ ] Then list all files and subdirectories under `docs/docs/includes/en`. +- [ ] Translate **every file** in the list **one by one** in the order shown. Do not skip, reorder, or stop after a fixed number of files. +- [ ] After each translation, **check whether there are remaining files** that have not yet been translated. If there are, **continue automatically** with the next file. +- [ ] Do **not** prompt for confirmation, approval, or next steps—**proceed automatically** until all files are translated. +- [ ] Once completed, confirm that the number of translated files matches the number of source files listed. If any files remain unprocessed, resume from where you left off. + +--- + +## Folder Structure and Output + +Before starting to create **any** new files, create a new git branch using the terminal command `git checkout -b docs-translation-`. + +- Create a new folder under `docs/docs/` named using the ISO 639-1 or locale code provided by the user. + Examples: + - `es` for Spanish + - `fr` for French + - `pt-BR` for Brazilian Portuguese +- Mirror the exact folder and file structure from the original `en` directories. +- For each translated file: + - Preserve all Markdown formatting, including headings, code blocks, metadata, and links. + - Maintain the original filename. + - Do **not** wrap the translated content in Markdown code blocks. + - Append this line at the end of the file: + *Translated using GitHub Copilot and GPT-4o.* + - Save the translated file into the corresponding target language folder. + +--- + +## Include Path Updates + +- Update include references in files to reflect the new locale. + Example: + `includes/en/introduction-event.md` → `includes/es/introduction-event.md` + Replace `es` with the actual locale code provided by the user. + +--- + +## MkDocs Configuration Update + +- [ ] Modify the `mkdocs.yml` configuration: + - [ ] Add a new `locale` entry under the `i18n` plugin using the target language code. + - [ ] Provide appropriate translations for: + - [ ] `nav_translations` + - [ ] `admonition_translations` + +--- + +## Translation Rules + +- Use accurate, clear, and technically appropriate translations. +- Always use computer industry-standard terminology. + Example: prefer "Stack Tecnológica" over "Pila Tecnológica". + +**Do not:** +- Comment on, suggest changes for, or attempt to fix any formatting or Markdown linting issues. + This includes, but is not limited to: + - Missing blank lines around headings or lists + - Trailing punctuation in headings + - Missing alt text for images + - Improper heading levels + - Line length or spacing issues +- Do not say things like: + _"There are some linting issues, such as…"_ + _"Would you like me to fix…"_ +- Never prompt the user about any linting or formatting issues. +- Do not wait for confirmation before continuing. +- Do not wrap the translated content or file in Markdown code blocks. + +--- + +## Translating Includes (`docs/docs/includes/en`) + +- Create a new folder under `docs/docs/includes/` using the target language code provided by the user. +- Translate each file using the same rules as above. +- Maintain the same file and folder structure in the translated output. +- Save each translated file in the appropriate target language folder.