Add translation management tool suite and update Chinese translations

- Introduced a comprehensive guide for the translation management tool suite, detailing components, usage, and best practices. - Added `translation-manager.py`, `translation-cleaner.py`, and `manage-translations.sh` scripts for managing translations. - Updated the Chinese translation file (`zh_CN.json`) to improve existing translations and remove unused keys. - Enhanced documentation with examples and troubleshooting tips for better user experience.
2025-06-17 14:29:33 +08:00
parent b32734b9f5
commit 89e25e3504
8 changed files with 1348 additions and 661 deletions
@@ -0,0 +1,111 @@
+# Translation Management Tools
+
+This directory contains a toolset for managing project translation files.
+
+## Directory Structure
+
+```
+translations/
+├── tools/                          # Translation management tools directory
+│   ├── translation-manager.py      # Main translation manager
+│   ├── translation-cleaner.py      # Translation maintenance tool
+│   ├── manage-translations.sh      # Convenient wrapper script
+│   ├── translation-tools-guide.md  # Detailed usage documentation
+│   └── README.md                   # This file
+├── en_US.json                      # English translation file
+├── zh_CN.json                      # Chinese translation file
+└── ...                             # Other language files
+```
+
+## Quick Start
+
+### Running from tools directory
+
+```bash
+# Enter tools directory
+cd .config/quickshell/translations/tools
+
+# Check current translation status
+./manage-translations.sh status
+
+# Update all translation files
+./manage-translations.sh update
+
+# Update specific language
+./manage-translations.sh update -l zh_CN
+
+# Clean unused keys
+./manage-translations.sh clean
+
+# Sync all language files
+./manage-translations.sh sync
+```
+
+### Running from project root directory
+
+```bash
+# Run from project root directory (recommended to use relative paths)
+.config/quickshell/translations/tools/manage-translations.sh status
+.config/quickshell/translations/tools/manage-translations.sh update
+```
+
+## Tool Description
+
+### 🛠️ `manage-translations.sh` - Main Entry Point
+Convenient command-line interface that integrates all translation management functions.
+
+### 🔍 `translation-manager.py` - Core Manager
+- Extract translatable texts
+- Compare translation file differences
+- Interactive translation updates
+
+### 🧹 `translation-cleaner.py` - Maintenance Tool
+- Clean unused translation keys
+- Sync language file structure
+- Create backup files
+
+## Common Workflows
+
+### After adding new translatable texts
+```bash
+./manage-translations.sh update
+```
+
+### Clean up after code refactoring
+```bash
+./manage-translations.sh clean
+```
+
+### Add new language
+```bash
+./manage-translations.sh update -l new_language_code
+```
+
+### Check translation status
+```bash
+./manage-translations.sh status
+```
+
+## Documentation
+
+- 📖 [Detailed Usage Guide](./translation-tools-guide.md)
+
+## Important Notes
+
+1. **Running Location**: Tools automatically detect relative paths, can be run from tools directory or project root
+2. **Backup**: Cleanup operations automatically create backup files
+3. **Encoding**: All files use UTF-8 encoding
+4. **Permissions**: Ensure scripts have execution permissions
+
+## Supported Translation Formats
+
+The tool recognizes translatable texts in the following formats:
+```qml
+qsTr("Your text here")
+qsTr('Single quotes work too')
+i18n.t("JavaScript translations")
+```
+
+---
+
+If you have any issues, please refer to the detailed documentation or check error messages in script output.