kinemotion 0.58.0__tar.gz → 0.59.1__tar.gz

kinemotion-0.59.1/.basic-memory/development/i18n-implementation-plan-for-validation-messages.md

@@ -0,0 +1,102 @@
+---
+title: i18n Implementation Plan for Validation Messages
+type: note
+permalink: development/i18n-implementation-plan-for-validation-messages
+---
+
+# Internationalization (i18n) Implementation Plan for Validation Messages
+
+## Executive Summary
+
+Implementing i18n for validation messages in the Kinemotion backend using **Option B: Structured Data + Frontend Translation** approach. This decouples the backend from translation logic and aligns with REST API best practices.
+
+## Current State Analysis
+
+### Validator Structure
+- **Location**: `src/kinemotion/cmj/metrics_validator.py` and `src/kinemotion/dropjump/metrics_validator.py`
+- **ValidationResult Flow**:
+  1. Validators generate formatted messages: `"Flight time 0.600s within expected range for recreational"`
+  2. Messages stored in `ValidationIssue` objects with metric, value, bounds, severity
+  3. Sent to frontend via `CMJMetrics.validation_result` → `to_dict()`
+
+### Current Message Examples
+```python
+# ERROR
+result.add_error("flight_time", f"Flight time {flight_time:.3f}s below frame rate resolution limit")
+
+# WARNING
+result.add_warning("flight_time", f"Flight time {flight_time:.3f}s outside typical range [{min:.3f}-{max:.3f}]s for {profile}")
+
+# INFO
+result.add_info("flight_time", f"Flight time {flight_time:.3f}s within expected range for {profile}")
+```
+
+### Metrics with Validation Messages
+**CMJ Validator** (16 validation methods):
+- Multiple validation checks generating 30+ message variants
+
+**Drop Jump Validator** (6 validation methods):
+- Multiple validation checks generating 15+ message variants
+
+## Design: Structured Data Approach (Option B)
+
+### Why This Approach?
+- Decouples backend from translation logic
+- Stable API contract (language-independent)
+- Frontend-only updates for new languages
+- Follows REST API best practices
+- Separates concerns: backend = validation logic, frontend = presentation/translation
+
+## New Validation Response Structure
+
+**After (Proposed)**:
+```json
+{
+  "status": "PASS_WITH_WARNINGS",
+  "issues": [
+    {
+      "severity": "warning",
+      "metric": "flight_time",
+      "message_key": "validation.flight_time.outside_range",
+      "value": 0.600,
+      "bounds": [0.400, 0.500],
+      "context": {
+        "min": 0.400,
+        "max": 0.500,
+        "profile": "recreational",
+        "unit": "s"
+      }
+    }
+  ],
+  "athlete_profile": "recreational"
+}
+```
+
+## Message Key Naming Convention
+
+Pattern: `validation.[metric].[condition]`
+
+Examples:
+- `validation.flight_time.within_range` - Value in expected range (INFO)
+- `validation.flight_time.outside_range` - Value outside but physically possible (WARNING)
+- `validation.flight_time.below_minimum` - Below frame rate resolution (ERROR)
+- `validation.jump_height.no_jump` - Essentially no jump detected (ERROR)
+
+## Implementation Summary
+
+### Phase 1: Backend Changes
+1. Add `message_key` and `context` fields to `ValidationIssue`
+2. Update `add_error()`, `add_warning()`, `add_info()` methods
+3. Update all 22 validation methods in both validators
+4. Update `to_dict()` serialization
+
+### Phase 2: Frontend Changes
+1. Create translation files (en, es, fr, de, ja, etc.)
+2. Implement i18next or react-intl
+3. Update ValidationIssue component to use message_key + context
+4. Add language selection UI
+
+### Phase 3: Backward Compatibility
+- Keep `message` field for old clients
+- Message_key is optional
+- Gradual migration over 2-3 releases

kinemotion-0.59.1/.basic-memory/project-management/i18n-documentation-cleanup-completed.md

@@ -0,0 +1,102 @@
+---
+title: i18n Documentation Cleanup - Completed
+type: note
+permalink: project-management/i18n-documentation-cleanup-completed
+---
+
+# i18n Documentation Cleanup - Completed ✅
+
+**Date**: December 14, 2024
+**Status**: Complete with all tests passing (70/70)
+
+## What Was Cleaned Up
+
+### 1. Deleted Redundant Files (11 files)
+**From frontend/ directory:**
+- `I18N_ARCHITECTURE.md`
+- `I18N_IMPLEMENTATION_GUIDE.md`
+- `I18N_QUICK_START.md`
+- `I18N_SUMMARY.md`
+- `I18N_TESTING_GUIDE.md`
+- `I18N-FEATURE-COMPLETE.md`
+- `I18N-SETUP-COMPLETE.md`
+- `I18N-TESTS-SUMMARY.md`
+- `README_I18N.md`
+
+**From project root:**
+- `I18N_DELIVERABLES.md`
+- `I18N_IMPLEMENTATION_SUMMARY.txt`
+
+**Reason**: These were documentation artifacts from the implementation process. Information is redundant with actual code and source of truth.
+
+### 2. Retained & Clarified Documentation (6 files)
+**Location**: `docs/development/i18n-*.md`
+
+All files relate to **v0.60.0 future work** - backend internationalization of validation messages:
+- `I18N-README.md` (updated with forward-looking notice)
+- `i18n-summary.md`
+- `i18n-quick-start-guide.md`
+- `i18n-cheat-sheet.md`
+- `i18n-architecture-diagram.md`
+- `i18n-validation-messages-specification.md`
+
+**Update Made**: Added warning header to `I18N-README.md` clarifying:
+- These docs are for **v0.60.0 roadmap work** (backend message i18n)
+- Current implementation (v0.58.0) frontend UI i18n is in actual source code
+- Users should refer to `frontend/` components for current implementation
+
+### 3. Basic Memory Documentation
+**Location**: `.basic-memory/development/i18n-implementation-plan-for-validation-messages.md`
+
+This is properly placed and serves as internal reference material.
+
+## Current State
+
+### Frontend i18n (COMPLETED - v0.58.0)
+✅ Implementation files:
+- `src/i18n/config.ts`
+- `src/hooks/useLanguage.ts` & tests
+- `src/components/LanguageSwitcher.tsx` & tests
+- `src/i18n/locales/` - Translation files (en, es, fr)
+
+✅ All 70 tests passing:
+- 7 test files
+- 70 test functions
+- Components, hooks, and integration tests
+
+### Backend i18n (PLANNED - v0.60.0)
+📋 Documentation in `docs/development/i18n-*.md`:
+- Complete specification for adding i18n support to validation messages
+- Step-by-step implementation guide
+- Architecture diagrams
+- Testing strategy
+
+## Verification Results
+
+```
+Test Files  7 passed (7)
+Tests       70 passed (70)
+No broken imports or references
+All existing tests unaffected
+```
+
+## Best Practices Applied
+
+1. **Single Source of Truth**: Documentation in `docs/` for future work, implementation in source code
+2. **Clear Separation**: Frontend (current) vs Backend (future) clearly distinguished
+3. **Reduced Clutter**: Removed process artifacts, kept reference material
+4. **Proper Organization**: Future work docs properly indexed with clear reading guides
+
+## Final Adjustments
+
+✅ Removed specific version references from future-work docs:
+- Changed "v0.60.0" to generic descriptions ("minor version bump", "future release")
+- Updated migration timeline to use phases instead of version numbers
+- Changed deployment steps to use placeholders instead of specific tags
+- This allows the docs to remain accurate regardless of when the feature is implemented
+
+## Next Steps
+
+- When implementing backend i18n, follow guides in `docs/development/i18n-*.md`
+- Update basic memory with progress on backend implementation
+- Docs are version-agnostic and ready for future use

{kinemotion-0.58.0 → kinemotion-0.59.1}/.claude/settings.local.json

@@ -1,5 +1,9 @@
 {
   "includeCoAuthoredBy": false,
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  },
   "permissions": {
     "allow": [
       "Bash(cat:*)",
@@ -22,7 +26,7 @@
       "WebFetch(domain:docs.sonarsource.com)",
       "WebFetch(domain:github.com)",
       "WebFetch(domain:pypi.org)",
-      "WebFetch(domain:raw.githubusercontent.com)"
+      "WebFetch(domain:raw.githubusercontent.com)",
       "WebFetch(domain:realpython.com)",
       "WebFetch(domain:sonarcloud.io)",
       "WebFetch(domain:www.pyopensci.org)",
@@ -68,7 +72,7 @@
       "mcp__sonarqube__search_sonar_issues_in_projects",
       "mcp__sonarqube__show_rule",
       "mcp__web-search__freebird_fetch",
-      "mcp__web-search__freebird_search",
+      "mcp__web-search__freebird_search"
     ]
   },
   "enableAllProjectMcpServers": true

{kinemotion-0.58.0 → kinemotion-0.59.1}/.gitignore

@@ -59,6 +59,7 @@ coverage.xml
 !pyproject.toml
 !vercel.json
 !frontend/package.json
+!frontend/src/i18n/locales/**/*.json
 
 # Documentation build output
 site/

{kinemotion-0.58.0 → kinemotion-0.59.1}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## kinemotion-v0.59.1 (2025-12-15)
+
+### Fix
+
+- add missing i18n translation JSON files to git
+
+## kinemotion-v0.59.0 (2025-12-15)
+
+### Feat
+
+- add comprehensive frontend i18n support with 3 languages
+
 ## kinemotion-v0.58.0 (2025-12-14)
 
 ### Feat

{kinemotion-0.58.0 → kinemotion-0.59.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.58.0
+Version: 0.59.1
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

kinemotion-0.59.1/docs/development/I18N-README.md

@@ -0,0 +1,327 @@
+# Internationalization (i18n) Implementation Guide
+
+**⚠️ IMPORTANT**: This guide covers **future work** - internationalization of backend validation messages.
+
+**Currently Completed**: Frontend UI i18n for user-facing strings (English, Spanish, French). See `frontend/` components for current implementation.
+
+______________________________________________________________________
+
+## Document Index
+
+This documentation is for implementing **backend validation message i18n** (future roadmap item).
+
+### 1. **Summary** - Start Here
+
+📄 **File**: `i18n-summary.md`
+
+**What to read**: Executive overview, implementation scope, timeline
+**Time to read**: 10 minutes
+**Key sections**:
+
+- Why Option B (Structured Data) is recommended
+- What gets implemented (backend + frontend)
+- Implementation scope and effort estimate
+- JSON response example
+- Backward compatibility guarantee
+
+**Best for**: Understanding the overall approach and getting buy-in from stakeholders
+
+______________________________________________________________________
+
+### 2. **Specification** - Complete Technical Reference
+
+📄 **File**: `i18n-validation-messages-specification.md`
+
+**What to read**: Detailed technical specs, data models, implementation details
+**Time to read**: 30-45 minutes
+**Key sections**:
+
+- Architecture decision rationale (Option A vs B)
+- Data model changes (ValidationIssue, ValidationResult)
+- Message key naming convention
+- Backend implementation (step-by-step code changes)
+- Frontend implementation (i18next setup, components)
+- Testing strategy with code examples
+- Migration checklist
+- Complete message key reference
+
+**Best for**: Developers implementing the feature, code reviewers, QA engineers
+
+______________________________________________________________________
+
+### 3. **Quick Start Guide** - Step-by-Step Implementation
+
+📄 **File**: `i18n-quick-start-guide.md`
+
+**What to read**: Actionable implementation steps, code templates
+**Time to read**: 20-30 minutes for overview, reference during implementation
+**Key sections**:
+
+- Phase 1: Backend implementation (6 steps)
+- Phase 2: Frontend implementation (5 steps)
+- Phase 3: Integration testing
+- Detailed code examples for each step
+- Testing code snippets
+- Implementation checklist
+- Deployment steps
+- Rollback plan
+
+**Best for**: Developers actually implementing the feature (use as a guide)
+
+______________________________________________________________________
+
+### 4. **Architecture Diagram** - Visual Guide
+
+📄 **File**: `i18n-architecture-diagram.md`
+
+**What to read**: Visual representations of data flow, component architecture
+**Time to read**: 15-20 minutes
+**Key sections**:
+
+- Data flow from video upload to rendered UI
+- Component architecture diagram
+- Message key resolution flow
+- Message key namespace structure
+- Backward compatibility timeline
+- Language auto-detection strategy
+- Testing strategy matrix
+
+**Best for**: Understanding how components interact, architectural decisions, planning
+
+______________________________________________________________________
+
+### 5. **Cheat Sheet** - Quick Reference
+
+📄 **File**: `i18n-cheat-sheet.md`
+
+**What to read**: Quick reference during implementation
+**Time to read**: 5-10 minutes (for quick lookup)
+**Key sections**:
+
+- Quick reference code snippets
+- Message key patterns
+- JSON response fields
+- Translation template placeholders
+- Code changes summary
+- Time estimates
+- Common mistakes to avoid
+- Validation checklist
+
+**Best for**: Developers implementing the feature (bookmark and print!)
+
+______________________________________________________________________
+
+## Reading Recommendations
+
+### For Developers
+
+1. Start with **Summary** (10 min) - understand the approach
+1. Read **Quick Start Guide** (30 min) - get implementation steps
+1. Keep **Cheat Sheet** open during implementation (reference as needed)
+1. Reference **Specification** (30 min) - for detailed info on specific changes
+
+### For Project Managers
+
+1. Start with **Summary** (10 min) - understand scope and timeline
+1. Review **Quick Start Guide** checklist (5 min) - track progress
+
+### For QA/Testing Engineers
+
+1. Start with **Summary** (10 min) - understand the feature
+1. Read **Specification** testing strategy section (10 min) - understand test approach
+1. Reference **Quick Start Guide** testing section (10 min) - test code examples
+1. Use **Cheat Sheet** validation checklist (5 min) - test execution
+
+### For Code Reviewers
+
+1. Read **Summary** (10 min) - understand the approach
+1. Read **Specification** sections 1-2 (15 min) - understand data model changes
+1. Reference **Specification** code implementation sections (as needed)
+1. Use **Cheat Sheet** common mistakes (5 min) - what to look for
+
+### For Architects/Decision Makers
+
+1. Read **Summary** (10 min)
+1. Review **Architecture Diagram** (15 min)
+1. Check **Backward Compatibility** section (5 min)
+
+______________________________________________________________________
+
+## Key Facts at a Glance
+
+| Aspect              | Detail                                                  |
+| ------------------- | ------------------------------------------------------- |
+| **Approach**        | Option B: Structured Data + Frontend Translation        |
+| **Breaking Change** | No - Fully backward compatible                          |
+| **New Version**     | v0.60.0 (minor version bump)                            |
+| **Effort**          | 14-20 hours (backend 4-6h, frontend 6-8h, testing 4-6h) |
+| **Files to Change** | 5 backend + 10 frontend files                           |
+| **Message Keys**    | ~45-50 (organized by metric)                            |
+| **Languages**       | 5 (en, es, fr, de, ja)                                  |
+| **Tests**           | 10-20 new tests (backend + frontend)                    |
+| **Backward Compat** | Yes - message field still works                         |
+
+______________________________________________________________________
+
+## Implementation Checklist
+
+### Before Starting
+
+- [ ] Read Summary (i18n-summary.md)
+- [ ] Read Quick Start Guide (i18n-quick-start-guide.md)
+- [ ] Print Cheat Sheet (i18n-cheat-sheet.md)
+- [ ] Review Architecture (i18n-architecture-diagram.md)
+
+### Phase 1: Backend
+
+- [ ] Update ValidationIssue dataclass
+- [ ] Update add_error/add_warning/add_info methods
+- [ ] Update CMJ validator (16 methods)
+- [ ] Update Drop Jump validator (6 methods)
+- [ ] Update serialization (to_dict)
+- [ ] Add backend tests
+- [ ] Run full test suite
+- [ ] Verify backward compatibility
+
+### Phase 2: Frontend
+
+- [ ] Create translation files (5 languages)
+- [ ] Install i18next + react-i18next
+- [ ] Setup i18next configuration
+- [ ] Update ValidationIssue component
+- [ ] Add language selector (optional)
+- [ ] Add frontend tests
+- [ ] Run linting and type checks
+
+### Phase 3: Integration
+
+- [ ] Run E2E tests
+- [ ] Test all languages
+- [ ] Verify number formatting
+- [ ] Test language switching
+- [ ] Test URL parameters
+- [ ] Test localStorage persistence
+- [ ] Verify message key completeness
+
+### Pre-Release
+
+- [ ] All tests passing (620+ backend, frontend tests)
+- [ ] No type errors (pyright strict)
+- [ ] No linting errors (ruff)
+- [ ] Code review complete
+- [ ] Documentation updated
+- [ ] CHANGELOG updated
+
+______________________________________________________________________
+
+## FAQ
+
+**Q: Why Option B (Structured Data) instead of Option A (Backend Translation)?**
+A: See Summary section "Why This Approach?" - better separation of concerns, scalability, maintainability.
+
+**Q: Is this a breaking change?**
+A: No. The `message` field continues to work. This is backward compatible.
+
+**Q: How long does implementation take?**
+A: 14-20 hours total (backend 4-6h, frontend 6-8h, testing 4-6h).
+
+**Q: What if I only want to support 2 languages?**
+A: Just create 2 translation files. The system is flexible.
+
+**Q: Do I need to update every validator method?**
+A: Yes. All 22 validation methods should be updated for consistency.
+
+**Q: Can I implement this incrementally?**
+A: Yes. Phase 1 (backend) can be deployed as v0.60.0 with both message and message_key fields. Phase 2 (frontend) can be deployed separately.
+
+**Q: What happens to old clients?**
+A: They continue using the `message` field, which is still populated. No issues.
+
+**Q: How do I test this locally?**
+A: See Quick Start Guide section on testing.
+
+**Q: When should I do this?**
+A: Recommended for v0.60.0 release (after MVP validation).
+
+______________________________________________________________________
+
+## Document Sizes
+
+| Document                     | Pages  | Read Time       |
+| ---------------------------- | ------ | --------------- |
+| i18n-summary.md              | 10     | 10 min          |
+| i18n-specification.md        | 20     | 30-45 min       |
+| i18n-quick-start-guide.md    | 15     | 20-30 min       |
+| i18n-architecture-diagram.md | 12     | 15-20 min       |
+| i18n-cheat-sheet.md          | 8      | 5-10 min        |
+| **Total**                    | **65** | **1.5-2 hours** |
+
+______________________________________________________________________
+
+## Implementation Timeline
+
+```
+Week 1 (Backend Implementation)
+├─ Day 1: Update core validation.py
+├─ Day 2: Update CMJ validator
+├─ Day 3: Update Drop Jump validator
+├─ Day 4: Serialization + testing
+└─ Day 5: Code review + fixes
+
+Week 2 (Frontend Implementation)
+├─ Day 1: Create translation files
+├─ Day 2: Setup i18next
+├─ Day 3: Update components
+├─ Day 4: Testing + fixes
+└─ Day 5: Integration testing
+
+Week 3 (QA & Release)
+├─ Day 1-2: Full testing cycle
+├─ Day 3: Documentation
+├─ Day 4: Code review
+└─ Day 5: Release (v0.60.0)
+```
+
+______________________________________________________________________
+
+## Key Contacts
+
+- **Architecture Questions**: See i18n-architecture-diagram.md
+- **Implementation Help**: See i18n-quick-start-guide.md
+- **Detailed Specs**: See i18n-validation-messages-specification.md
+- **Quick Reference**: See i18n-cheat-sheet.md
+
+______________________________________________________________________
+
+## Version History
+
+| Version | Date       | Changes               |
+| ------- | ---------- | --------------------- |
+| 1.0     | 2024-12-14 | Initial specification |
+
+______________________________________________________________________
+
+## Related Documentation
+
+- **Project Roadmap**: `docs/strategy/MVP_VALIDATION_CHECKPOINTS.md`
+- **Testing Guide**: `docs/development/testing.md`
+- **Type Hints Guide**: `docs/development/type-hints.md`
+- **Agents Guide**: `docs/development/agents-guide.md`
+
+______________________________________________________________________
+
+## Next Steps
+
+1. **Read Summary** (10 minutes)
+1. **Share with team** for feedback
+1. **Create feature branch**: `feat/i18n-validation-messages`
+1. **Follow Quick Start Guide** for implementation
+1. **Track progress** using implementation checklist above
+1. **Request code review** following specification
+1. **Deploy to production** as v0.60.0
+
+______________________________________________________________________
+
+**Status**: ✅ Complete
+**Last Updated**: 2024-12-14
+**Maintained By**: Kinemotion Development Team