From 054c41fcec44da2255ab529c80b7a984dddac5b2 Mon Sep 17 00:00:00 2001 From: SuperKali Date: Fri, 26 Dec 2025 21:59:18 +0100 Subject: [PATCH] refactor: organize scripts into dedicated directories - Move build scripts (build-*.sh) to scripts/build/ directory - Move sync-locales.js to scripts/locales/ directory - Update GitHub workflow to reference new script paths - Improve DEVELOPMENT.md with new script paths and detailed Project Structure - Remove obsolete scripts/README.md --- .github/workflows/sync-locales.yml | 2 +- DEVELOPMENT.md | 124 +++++++++---- scripts/README.md | 244 -------------------------- scripts/{ => build}/build-all.sh | 0 scripts/{ => build}/build-linux.sh | 0 scripts/{ => build}/build-macos.sh | 0 scripts/{ => locales}/sync-locales.js | 0 7 files changed, 93 insertions(+), 277 deletions(-) delete mode 100644 scripts/README.md rename scripts/{ => build}/build-all.sh (100%) rename scripts/{ => build}/build-linux.sh (100%) rename scripts/{ => build}/build-macos.sh (100%) rename scripts/{ => locales}/sync-locales.js (100%) diff --git a/.github/workflows/sync-locales.yml b/.github/workflows/sync-locales.yml index a7498d8..162112e 100644 --- a/.github/workflows/sync-locales.yml +++ b/.github/workflows/sync-locales.yml @@ -32,7 +32,7 @@ jobs: OPENAI_TIER: ${{ vars.OPENAI_TIER || 'free' }} RETRY_FAILED: ${{ vars.RETRY_FAILED || 'false' }} run: | - node scripts/sync-locales.js + node scripts/locales/sync-locales.js continue-on-error: true - name: Check for changes diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 4dcd8ec..a98fe5b 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -104,23 +104,23 @@ npm run tauri:dev ### Single Platform ```bash -./scripts/build-macos.sh # macOS (Intel + ARM) -./scripts/build-linux.sh # Linux (x64 + ARM) -npm run tauri:build # Windows +./scripts/build/build-macos.sh # macOS (Intel + ARM) +./scripts/build/build-linux.sh # Linux (x64 + ARM) +npm run tauri:build # Windows ``` ### All Platforms ```bash -./scripts/build-all.sh +./scripts/build/build-all.sh ``` ### Build Options ```bash -./scripts/build-macos.sh --clean # Clean build -./scripts/build-macos.sh --dev # Debug symbols -./scripts/build-macos.sh --clean --dev # Both +./scripts/build/build-macos.sh --clean # Clean build +./scripts/build/build-macos.sh --dev # Debug symbols +./scripts/build/build-macos.sh --clean --dev # Both ``` ### Output @@ -132,46 +132,106 @@ npm run tauri:build # Windows ## Project Structure +### Directory Overview + ``` armbian-imager/ ├── src/ # React Frontend │ ├── components/ # UI Components -│ │ ├── flash/ # Flash progress -│ │ ├── layout/ # Header, HomePage -│ │ ├── modals/ # Board, Image, Device, Manufacturer +│ │ ├── flash/ # Flash progress components +│ │ │ ├── FlashActions.tsx # Action buttons (cancel, retry) +│ │ │ ├── FlashProgress.tsx # Progress display +│ │ │ └── FlashStageIcon.tsx # Stage indicators +│ │ ├── layout/ # Main layout +│ │ │ ├── Header.tsx # Top navigation bar +│ │ │ └── HomePage.tsx # Main page +│ │ ├── modals/ # Selection flow modals +│ │ │ ├── ManufacturerModal.tsx +│ │ │ ├── BoardModal.tsx +│ │ │ ├── ImageModal.tsx +│ │ │ └── DeviceModal.tsx │ │ └── shared/ # Reusable components -│ ├── hooks/ # React Hooks -│ ├── config/ # Badges, manufacturers, OS info -│ ├── locales/ # i18n (15 languages) +│ │ ├── AppVersion.tsx # Version display +│ │ ├── ErrorDisplay.tsx # Error presentation +│ │ ├── LoadingState.tsx # Loading indicators +│ │ └── SearchBox.tsx # Search functionality +│ ├── hooks/ # Custom React Hooks +│ │ ├── useTauri.ts # Tauri IPC wrappers +│ │ ├── useVendorLogos.ts # Logo validation +│ │ └── useAsyncData.ts # Async data fetching pattern +│ ├── config/ # Static configuration +│ │ ├── constants.ts # App constants +│ │ ├── deviceColors.ts # Device color mapping +│ │ └── os-info.ts # OS information +│ ├── locales/ # i18n translations (15 languages) │ ├── styles/ # Modular CSS +│ │ ├── theme.css # Theme variables (light/dark) +│ │ ├── components.css # Component styles +│ │ └── responsive.css # Responsive design │ ├── types/ # TypeScript interfaces -│ ├── utils/ # Utilities -│ └── assets/ # Images, logos, icons +│ ├── utils/ # Utility functions +│ ├── assets/ # Static assets +│ ├── App.tsx # Main app component +│ └── main.tsx # React entry point │ ├── src-tauri/ # Rust Backend │ ├── src/ -│ │ ├── commands/ # Tauri IPC handlers -│ │ ├── config/ # Configuration -│ │ ├── devices/ # Device detection -│ │ ├── flash/ # Platform flash implementations -│ │ ├── images/ # Image management +│ │ ├── commands/ # Tauri IPC command handlers +│ │ │ ├── board_queries.rs # Board/image API queries +│ │ │ ├── operations.rs # Download & flash operations +│ │ │ ├── custom_image.rs # Custom image handling +│ │ │ ├── progress.rs # Progress event emission +│ │ │ ├── system.rs # System utilities +│ │ │ └── state.rs # Shared application state +│ │ ├── devices/ # Platform-specific device detection +│ │ │ ├── linux.rs # Linux (UDisks2) +│ │ │ ├── macos.rs # macOS (diskutil) +│ │ │ └── windows.rs # Windows (WMI) +│ │ ├── flash/ # Platform-specific flash operations +│ │ │ ├── linux/ # Linux implementation +│ │ │ ├── macos/ # macOS implementation +│ │ │ └── windows/ # Windows implementation +│ │ ├── images/ # Image file management │ │ ├── logging/ # Session logging -│ │ ├── paste/ # Log upload -│ │ ├── utils/ # Utilities -│ │ ├── download.rs # HTTP downloads -│ │ └── decompress.rs # XZ, GZ, ZSTD -│ ├── icons/ # App icons +│ │ ├── paste/ # Log upload service +│ │ ├── utils/ # Rust utilities +│ │ ├── download.rs # HTTP streaming downloads +│ │ ├── decompress.rs # Archive extraction +│ │ └── main.rs # Rust entry point +│ ├── icons/ # App icons (all platforms) +│ ├── Cargo.toml # Rust dependencies +│ ├── tauri.conf.json # Tauri configuration │ └── target/ # Compiled binaries (gitignored) │ -├── scripts/ # Build and setup -│ ├── build-*.sh # Platform build scripts +├── scripts/ # Build and utility scripts +│ ├── build/ # Platform build scripts +│ │ ├── build-all.sh # All platforms +│ │ ├── build-linux.sh # Linux builds +│ │ └── build-macos.sh # macOS universal binaries +│ ├── locales/ # Locale management +│ │ └── sync-locales.js # Translation sync script │ └── setup/ # Dependency installation -│ ├── install.sh -│ ├── install-linux.sh -│ ├── install-macos.sh -│ └── install-windows.ps1 +│ ├── install.sh # Universal installer +│ ├── install-linux.sh # Linux dependencies +│ ├── install-macos.sh # macOS dependencies +│ └── install-windows.ps1 # Windows dependencies │ -└── .github/workflows/ # CI/CD +├── .github/workflows/ # CI/CD pipelines +│ ├── build.yml # CI builds +│ ├── build-artifacts.yml # Release builds +│ ├── pr-check.yml # PR validation +│ └── sync-locales.yml # Auto translation sync +│ +├── public/ # Static assets +│ └── locales/ # i18n fallback data +│ +├── docs/ # Additional documentation +├── images/ # Project images/screenshots +├── package.json # Node dependencies & scripts +│ +├── CONTRIBUTING.md # Contribution guidelines +├── DEVELOPMENT.md # This file +└── README.md # Project overview ``` --- diff --git a/scripts/README.md b/scripts/README.md deleted file mode 100644 index f2a089f..0000000 --- a/scripts/README.md +++ /dev/null @@ -1,244 +0,0 @@ -# Translation Sync Scripts - -This directory contains automation scripts for managing i18n translations. - -## sync-locales.js - -Automatically syncs all translation files with `src/locales/en.json` (the source of truth) and translates missing keys using AI. - -### Features - -- **Automatic Detection**: Finds missing keys in all locale files -- **AI Translation**: Uses OpenAI API to automatically translate new keys with high quality -- **Context-Aware**: Provides section/key context to the AI for better translations -- **Placeholder Preservation**: Maintains i18next placeholders like `{{count}}` and `{{boardName}}` -- **Adaptive Rate Limiting**: Automatically adjusts based on model and payment tier -- **Error Handling**: Falls back to `TODO:` prefix if translation fails -- **Smart Prompts**: Uses specialized prompts for technical UI translation - -### Usage - -#### Local Development - -```bash -# Basic usage (requires OpenAI API key) -export OPENAI_API_KEY=sk-... -node scripts/sync-locales.js - -# With custom model (default: gpt-4o-mini) -OPENAI_MODEL=gpt-4o node scripts/sync-locales.js - -# With custom OpenAI-compatible API endpoint -OPENAI_API=https://api.openai.com/v1 node scripts/sync-locales.js - -# For paid tier (much faster - 50-100x speedup) -OPENAI_TIER=paid node scripts/sync-locales.js - -# Retry failed translations (keys marked with TODO:) -RETRY_FAILED=true node scripts/sync-locales.js -``` - -#### GitHub Actions - -The workflow runs automatically: -- **Daily** at 00:00 UTC -- **On push** to the branch -- **On manual trigger** via workflow_dispatch - -### Configuration - -#### Environment Variables - -| Variable | Description | Default | Required | -|----------|-------------|---------|----------| -| `OPENAI_API_KEY` | OpenAI API key | - | Yes | -| `OPENAI_MODEL` | Model to use for translation | `gpt-4o-mini` | No | -| `OPENAI_API` | API endpoint URL | `https://api.openai.com/v1` | No | -| `OPENAI_TIER` | Account tier for rate limits | `free` | No | -| `RETRY_FAILED` | Retry keys marked with `TODO:` | `false` | No | - -#### GitHub Secrets/Variables - -To configure the GitHub Action: - -1. **Required - Add API key**: - ```bash - gh secret set OPENAI_API_KEY - ``` - -2. **Optional - Custom model** (for cost/quality tuning): - ```bash - gh variable set OPENAI_MODEL --value "gpt-4o-mini" - ``` - -3. **Optional - Custom endpoint** (for OpenAI-compatible APIs): - ```bash - gh variable set OPENAI_API --value "https://api.openai.com/v1" - ``` - -4. **Optional - Set account tier** (for faster translations with paid account): - ```bash - gh variable set OPENAI_TIER --value "paid" - ``` - -5. **Optional - Retry failed translations** (re-attempt keys marked with `TODO:`): - ```bash - gh variable set RETRY_FAILED --value "true" - ``` - -### OpenAI Setup - -#### Getting an API Key - -1. Visit [platform.openai.com](https://platform.openai.com/) -2. Sign up or log in -3. Navigate to API Keys section -4. Create a new API key -5. Add it to your environment or GitHub secrets - -#### Account Tier & Rate Limits - -The script automatically adjusts speed based on your account tier: - -| Tier | RPM Limit | Batch Size | Delay | 100 Keys Time | -|------|-----------|------------|-------|---------------| -| **Free** | 3/min | 1 | 21s | ~35 min | -| **Paid (Tier 1-2)** | 200/min | 50 | 300ms | ~1 min | -| **Paid (Tier 3-5)** | 500/min | 50 | 120ms | ~30 sec | - -To use paid tier rates: -1. Add a payment method to your OpenAI account (even $5 works) -2. Set `OPENAI_TIER=paid` environment variable - -**Recommendation**: With just a $5 balance, you get Tier 1-2 rates which are **65x faster** than free tier. - -#### Choosing a Model - -| Model | Cost | Quality | Speed | Best For | -|-------|------|---------|-------|----------| -| `gpt-4o-mini` | Low | High | Fast | Most translations (default) | -| `gpt-4o` | Medium | Very High | Fast | Complex UI text | -| `gpt-3.5-turbo` | Very Low | Medium | Very Fast | Simple translations | - -**Recommendation**: Start with `gpt-4o-mini` for the best balance of cost, quality, and speed. - -### Supported Languages - -| Code | Language | -|------|----------| -| `de` | German | -| `es` | Spanish | -| `fr` | French | -| `it` | Italian | -| `ja` | Japanese | -| `ko` | Korean | -| `nl` | Dutch | -| `pl` | Polish | -| `pt` | Portuguese | -| `ru` | Russian | -| `sl` | Slovenian | -| `tr` | Turkish | -| `uk` | Ukrainian | -| `zh` | Chinese (Simplified) | - -### Output - -The script will: -1. ✅ Show which keys are missing for each language -2. 🤖 Translate missing keys with OpenAI -3. 📊 Show translation statistics (success/failure) -4. ⚠️ Warn about any translation failures -5. 💾 Update locale files with translated content -6. 🔍 Exit with code 1 if changes were made (useful for CI/CD) - -### Example Output - -``` -🔍 Syncing translation files with en.json (source of truth) - -🤖 Using OpenAI API: https://api.openai.com/v1 -📦 Model: gpt-4o-mini -✅ API key is configured - -✅ Source file has 93 keys - -📝 Processing de (German)... - ✅ de is up to date (93 keys) - -📝 Processing hr (Croatian)... - ⚠️ Found 64 missing keys - 🤖 Translating 64 strings with OpenAI... - ✅ Updated hr with 64 new keys - -✨ Translation files updated successfully! - -📊 Summary: - - Total translated: 64 keys - - Please review translations for accuracy and context -``` - -### AI Translation Features - -The script uses specialized prompts to ensure: - -1. **Context Awareness**: Provides section/key context for each translation -2. **Technical Terminology**: Knows when to keep terms like "Flash", "SD card", "USB" in English -3. **Placeholder Preservation**: Maintains `{{variables}}` exactly as they appear -4. **UI Appropriateness**: Uses concise, natural text for buttons and labels -5. **Plural Forms**: Handles i18next plural suffixes (_one, _other) correctly -6. **Consistent Tone**: Maintains formal but friendly tone throughout - -### Best Practices - -1. **Review Translations**: AI translations are excellent but may need context-specific adjustments -2. **Test in App**: Always test translations in the actual application -3. **Handle Plurals**: The script preserves `_one` and `_other` suffixes for plural forms -4. **Check Placeholders**: Verify that `{{variables}}` are correctly preserved -5. **Cultural Nuances**: Review translations for cultural appropriateness -6. **Cost Management**: Use `gpt-4o-mini` for best cost/quality balance - -### Troubleshooting - -#### API Key Not Found - -``` -❌ OPENAI_API_KEY is not set! -``` - -**Solution**: Set the environment variable or GitHub secret: -```bash -export OPENAI_API_KEY=sk-... -``` - -#### Translation Failures - -If some translations fail with `TODO:`: -- Check your API key has sufficient credits -- Verify API endpoint is accessible -- Check rate limits (especially for larger translation batches - -#### Poor Quality Translations - -If translations seem off: -- The AI might lack specific UI context -- Try a more capable model like `gpt-4o` -- Manually edit the JSON files to fix issues -- Consider the translation context provided in the prompt - -#### Cost Concerns - -For cost optimization: -- Use `gpt-4o-mini` (very cost-effective) -- Run the script less frequently -- Review and merge translations in batches -- Consider caching previous translations - -### Cost Estimation - -Approximate costs for translating missing keys (using `gpt-4o-mini`): - -- **10 keys**: ~$0.00001 -- **50 keys**: ~$0.00005 -- **100 keys**: ~$0.0001 - -*Costs vary based on text length and model used.* diff --git a/scripts/build-all.sh b/scripts/build/build-all.sh similarity index 100% rename from scripts/build-all.sh rename to scripts/build/build-all.sh diff --git a/scripts/build-linux.sh b/scripts/build/build-linux.sh similarity index 100% rename from scripts/build-linux.sh rename to scripts/build/build-linux.sh diff --git a/scripts/build-macos.sh b/scripts/build/build-macos.sh similarity index 100% rename from scripts/build-macos.sh rename to scripts/build/build-macos.sh diff --git a/scripts/sync-locales.js b/scripts/locales/sync-locales.js similarity index 100% rename from scripts/sync-locales.js rename to scripts/locales/sync-locales.js